Port25™ Solutions, Inc.  
PowerMTA™ v4.0  
User's Guide  
Quick link to Directive Index  
Copyright © 1999-2012, Port25 Solutions, Inc. All Rights Reserved.  
Port25 and PowerMTA are trademarks of Port25 Solutions, Inc.  
All other brands and names are property of their respective owners.  
We welcome comments on this manual's form and content.  
Please send your comments to manuals@port25.com, including  
the manual's revision number: 2012-03-08-01.  
1
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
TABLE OF CONTENTS  
1. Introduction .............................................................................................................................................. 8  
1.1 General Description and Basic Functionality ..................................................................................... 8  
1.2 Minimum Requirements....................................................................................................................... 8  
1.3 Supported interfaces............................................................................................................................ 8  
1.4 Monitoring/Management Tools Summary ........................................................................................... 9  
2. PowerMTA Installation ......................................................................................................................... 10  
2.1 Installing on Microsoft Windows 2003/2008/7.................................................................................. 10  
2.2 Installing on Linux............................................................................................................................. 10  
2.2.1 System Limits on Linux............................................................................................................. 12  
2.3 Installing on Solaris........................................................................................................................... 12  
2.3.1 System Limits on Solaris ........................................................................................................... 13  
2.4 Initial Configuration.......................................................................................................................... 14  
2.4.1 IPv6............................................................................................................................................ 15  
2.5 Uninstalling ....................................................................................................................................... 15  
3. PowerMTA Configuration..................................................................................................................... 17  
3.1 Working with the Configuration File................................................................................................. 17  
3.2 Configuration Directives ................................................................................................................... 17  
3.2.1 Directive “Scope” Defined......................................................................................................... 18  
3.2.2 Directive “Type” defined........................................................................................................... 18  
3.2.3 Directive “Attribute” defined..................................................................................................... 19  
3.2.4 Directive “Default” defined ....................................................................................................... 19  
3.2.5 <global> Directives Defined...................................................................................................... 20  
3.2.6 <domain> Directives Defined.................................................................................................... 20  
3.2.7 <source> Directives Defined ..................................................................................................... 22  
3.2.8 <source-group> Directives Defined........................................................................................... 23  
3.2.9 <virtual-mta> Directives Defined .............................................................................................. 24  
3.2.10 <virtual-mta-pool> Directives Defined.................................................................................... 24  
3.2.11 <pattern-list> Directives Defined............................................................................................. 24  
3.2.12 <smtp-pattern-list> Directives Defined.................................................................................... 25  
3.2.13 <bounce-category-patterns> Directives Defined ..................................................................... 25  
3.2.14 <acct-file> Directives Defined................................................................................................. 25  
3.2.15 <smtp-user> Directives Defined .............................................................................................. 26  
3.2.16 <spool> Directives Defined ..................................................................................................... 28  
3.2.17 <bounce-processor> Directives Defined.................................................................................. 28  
3.2.18 <feedback-loop-processor> Directives Defined....................................................................... 28  
3.2.19 <address-list> Directives Defined............................................................................................ 29  
3.2.20 General Directives ................................................................................................................... 29  
3.2.21 Message Spool Directives........................................................................................................ 30  
3.2.22 Relaying Control Directives..................................................................................................... 32  
3.2.23 SMTP Service Directives......................................................................................................... 36  
3.2.24 Web-Based Monitor Directives................................................................................................ 56  
3.2.25 Logging Directives................................................................................................................... 57  
2
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3.2.26 Accounting Directives.............................................................................................................. 64  
3.2.27 General Queueing and Delivery Directives ............................................................................. 75  
3.2.28 SMTP Delivery Directives....................................................................................................... 95  
3.2.29 Discard Delivery Directives................................................................................................... 110  
3.2.30 File Delivery Directives......................................................................................................... 110  
3.2.31 Pipe Delivery Directives ........................................................................................................ 113  
3.2.32 Submission API Directives .................................................................................................... 114  
3.2.33 Source {Pickup}..................................................................................................................... 115  
3.2.34 Dummy SMTP ("blackholing") Directives............................................................................ 118  
3.2.35 Pattern List Directives............................................................................................................ 119  
3.2.36 SMTP Pattern List Directives ................................................................................................ 123  
3.2.37 Other Directives..................................................................................................................... 125  
4. PowerMTA Management..................................................................................................................... 131  
4.1 Management .................................................................................................................................... 131  
4.1.1 Monitoring ............................................................................................................................... 131  
4.1.2 Logging and Accounting.......................................................................................................... 131  
4.1.3 PowerMTA Startup and Shutdown .......................................................................................... 132  
4.2 Troubleshooting............................................................................................................................... 132  
4.2.1 Troubleshooting Startup Problems........................................................................................... 132  
4.2.2 Troubleshooting E-mail Delivery Problems ............................................................................ 134  
4.2.3 Troubleshooting DNS Name Resolution Problems.................................................................. 135  
4.2.4 Troubleshooting E-mail Reception/SMTP Feeding Problems................................................. 136  
4.2.5 In Case of a Crash.................................................................................................................... 136  
4.2.6 If All Else Fails........................................................................................................................ 136  
5. Web-Based Monitoring........................................................................................................................ 137  
5.1 Overview.......................................................................................................................................... 137  
5.2 Home Display .................................................................................................................................. 138  
5.3 Status Monitor Display.................................................................................................................... 140  
5.4 Queues Display................................................................................................................................ 143  
5.5 Queues “View Options” .................................................................................................................. 143  
5.6 Domains Display ............................................................................................................................. 145  
5.7 Domains “View Options”................................................................................................................ 146  
5.8 Common "Last Error"s.................................................................................................................... 146  
5.9 VirtualMTAs Display....................................................................................................................... 148  
5.10 Jobs Display .................................................................................................................................. 149  
5.11 Logs Display.................................................................................................................................. 150  
5.12 Listing of local IPs......................................................................................................................... 151  
5.13 Listing of emails in queue.............................................................................................................. 152  
6. Command Line Tool............................................................................................................................. 153  
6.1 Overview.......................................................................................................................................... 153  
6.2 Command Output Formats .............................................................................................................. 154  
6.2.1 Sample Command Outputs ...................................................................................................... 154  
3
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
6.3 Command Reference........................................................................................................................ 156  
6.3.1 clear dnscache............................................................................................................... 156  
6.3.2 check mfrom...................................................................................................................... 157  
6.3.3 check pra........................................................................................................................... 157  
6.3.4 reload.................................................................................................................................. 157  
6.3.5 reset counters............................................................................................................... 158  
6.3.6 reset status................................................................................................................... 158  
6.3.7 resolve............................................................................................................................... 158  
6.3.8 rotate acct...................................................................................................................... 160  
6.3.9 rotate log........................................................................................................................ 160  
6.3.10 schedule........................................................................................................................... 160  
6.3.11 set queue......................................................................................................................... 161  
6.3.12 show domains................................................................................................................. 161  
6.3.13 show queues.................................................................................................................... 162  
6.3.14 show jobs......................................................................................................................... 164  
6.3.15 show settings............................................................................................................... 164  
6.3.16 show status.................................................................................................................... 165  
6.3.17 show topdomains.......................................................................................................... 166  
6.3.18 show topqueues............................................................................................................. 166  
6.3.19 show version................................................................................................................. 166  
6.3.20 show vmtas...................................................................................................................... 167  
6.3.21 trace.................................................................................................................................. 167  
6.3.22 delete................................................................................................................................ 168  
6.3.23 pause.................................................................................................................................. 169  
6.3.24 resume................................................................................................................................ 169  
6.3.25 list.................................................................................................................................... 169  
6.3.26 license............................................................................................................................. 170  
6.3.27 deregister...................................................................................................................... 170  
6.3.28 register........................................................................................................................... 171  
6.3.29 show registration..................................................................................................... 172  
6.3.30 disable source............................................................................................................. 172  
6.3.31 enable source............................................................................................................... 172  
6.3.32 show disabled sources............................................................................................ 173  
7. Application Programming Interfaces ................................................................................................. 174  
7.1 Submission APIs .............................................................................................................................. 174  
7.1.1 Requirements ........................................................................................................................... 175  
7.1.2 Perl Submission API................................................................................................................ 175  
7.1.2.1 ConnectionReference ............................................................................................... 176  
7.1.2.2 MessageReference ...................................................................................................... 177  
7.1.2.3 RecipientReference.................................................................................................. 182  
7.1.3 Java Submission API ............................................................................................................... 184  
7.1.4 C++ Submission API ............................................................................................................... 184  
7.1.4.1 Method Reference ............................................................................................................ 184  
7.1.5 C Submission API.................................................................................................................... 191  
7.1.5.1 Function Reference .......................................................................................................... 192  
7.1.6 .NET Submission API.............................................................................................................. 209  
7.2 Migrating from the Old Submission APIs........................................................................................ 209  
7.2.1 Overview of Differences Between Old and New APIs............................................................ 209  
4
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
7.3 Accounting APIs .............................................................................................................................. 209  
7.4 Pickup Directory.............................................................................................................................. 209  
7.4.1 BSMTP files............................................................................................................................. 211  
7.5 Pipe Delivery ................................................................................................................................... 212  
7.5.1 Delivering mail to local users .................................................................................................. 213  
7.5.2 Pipe Delivery Programs Included With PowerMTA ............................................................... 213  
7.5.3 Accessing Files Created By The Sample Applications............................................................ 215  
7.5.4 Writing Your Own Pipe Delivery Programs............................................................................ 216  
7.6 Cold Fusion Tag (CFX_PMTA) ....................................................................................................... 217  
7.6.1 Sending E-mail With the CFX_PMTATag............................................................................... 217  
7.6.2 Compiling the CFX_PMTATag ............................................................................................... 220  
8. VirtualMTA Support ........................................................................................................................... 221  
8.1 Overview.......................................................................................................................................... 221  
8.2 VirtualMTA Definitions ................................................................................................................... 221  
8.3 VirtualMTA Pools............................................................................................................................ 222  
8.4 Selecting a VirtualMTA or VirtualMTA Pool .................................................................................. 223  
8.4.1 Selecting a VirtualMTA with a X-virtual-MTAHeader.................................................... 224  
8.4.2 Selecting a VirtualMTA by Regular Expression Matching ..................................................... 225  
8.4.3 Selecting a VirtualMTA by the IP Address/Port Receiving Connections................................ 227  
8.4.4 Selecting a VirtualMTA by the Source IP Address ................................................................. 229  
8.4.5 Selecting a VirtualMTA by a VirtualMTA IP address............................................................. 230  
8.5 Changing VirtualMTAs on the Fly................................................................................................... 230  
8.5.1 Changing a VirtualMTA.......................................................................................................... 230  
8.5.2 Cancelling a VirtualMTA ........................................................................................................ 231  
8.6 Configuring Additional IP Addresses.............................................................................................. 231  
8.6.1 Adjusting your Firewall Configuration.................................................................................... 232  
8.7 DNS Prerequisites ........................................................................................................................... 232  
9. Mailmerge Support .............................................................................................................................. 233  
9.1 Overview.......................................................................................................................................... 233  
9.2 Benefits ............................................................................................................................................ 233  
9.3 Configuration Requirements............................................................................................................ 234  
9.4 Creating Mailmerge Messages ........................................................................................................ 234  
9.4.1 Message Template and Mailmerge Variables .......................................................................... 234  
9.4.2 Reserved Variables .................................................................................................................. 235  
9.4.3 Merge Parts.............................................................................................................................. 236  
9.5 Submitting Mailmerge Messages..................................................................................................... 237  
9.5.1 API Submission ....................................................................................................................... 237  
9.5.2 Mailmerge SMTP extensions................................................................................................... 237  
9.5.3 Pickup Directory Submission................................................................................................... 239  
9.5.4 The XACKSMTP extension..................................................................................................... 240  
10. Advanced Features............................................................................................................................. 243  
10.1 Sender Reputation Monitoring....................................................................................................... 243  
5
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
10.1.1 Overview................................................................................................................................ 243  
10.1.2 Implementation ...................................................................................................................... 243  
10.1.3 Supporting commands............................................................................................................ 246  
10.2 SMTP AUTH support..................................................................................................................... 246  
10.2.1 Overview................................................................................................................................ 246  
10.2.2 Implementation for Inbound Connections.............................................................................. 246  
10.2.3 Implementation for Outbound Connections........................................................................... 248  
10.3 Sender-ID support ......................................................................................................................... 248  
10.3.1 Overview................................................................................................................................ 249  
10.3.2 Automated Authentic............................................................................................................. 249  
10.3.3 SUBMITTER Optimization................................................................................................... 250  
10.4 DomainKeys/DKIM support .......................................................................................................... 250  
10.4.1 Overview................................................................................................................................ 250  
10.4.2 PowerMTA's DomainKeys/DKIM Implementation .............................................................. 251  
10.4.3 DKIM signing based on values in a header............................................................................ 253  
10.5 Warming of IPs with Cold VirtualMTA ......................................................................................... 254  
10.5.1 Overview................................................................................................................................ 254  
10.6 Using of Bounce Category Patterns .............................................................................................. 256  
10.6.1 Overview................................................................................................................................ 256  
10.7 Combining domains with the same MX record(s) into one queue ................................................. 257  
10.7.1 Overview................................................................................................................................ 257  
10.8 Setting recipient priority................................................................................................................ 260  
10.8.1 Overview................................................................................................................................ 260  
10.9 SNMP Support ............................................................................................................................... 261  
10.9.1 Overview................................................................................................................................ 261  
11. The Accounting and Statistics ........................................................................................................... 262  
11.1 Introduction ................................................................................................................................... 262  
11.2 The Accounting File....................................................................................................................... 262  
11.2.1 Accounting records ................................................................................................................ 263  
11.2.2 "Successful delivered" Records ............................................................................................. 263  
11.2.3 “Bounced” Records................................................................................................................ 265  
11.2.4 “Transient error” Records ...................................................................................................... 266  
11.2.5 “Transient Queue” Records.................................................................................................... 268  
11.2.6 “Received” Records............................................................................................................... 269  
11.2.7 “Remote Bounce” & “Remote Status” Records..................................................................... 271  
11.2.8 “Feedback Loop” Records ..................................................................................................... 272  
11.2.9 Encoding ................................................................................................................................ 273  
11.3 Configuring the accounting file ..................................................................................................... 273  
11.3.1 Directives............................................................................................................................... 274  
11.3.2 Examples................................................................................................................................ 279  
11.4 The pmtastats Accounting Statistics Application..................................................................... 280  
11.4.1 pmtastatsOptions........................................................................................................... 280  
11.4.2 pmtastatsReport Breakdown ......................................................................................... 283  
11.4.2.1 Time Frame .................................................................................................................... 284  
11.4.2.2 Bounce Categories.......................................................................................................... 284  
11.4.2.3 Delivery Times............................................................................................................... 284  
6
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
11.4.2.4 Message Counts.............................................................................................................. 286  
11.4.2.5 Top Bounce.................................................................................................................... 286  
11.4.2.6 Top Domains.................................................................................................................. 287  
11.4.2.7 Top Rates ....................................................................................................................... 289  
11.4.2.8 VMTA Summary............................................................................................................ 290  
11.4.2.9 VMTA Time Breakdown ............................................................................................... 291  
11.4.2.10 VMTA Top Bounces.................................................................................................... 292  
11.5 The acctfind Accounting Reporting Application...................................................................... 292  
11.5.1 Examples................................................................................................................................ 294  
11.6 Bounce Categories......................................................................................................................... 295  
11.7 Libraries Available for Parsing CSV Records............................................................................... 297  
12. Processing Inbound email.................................................................................................................. 299  
12.1 Introduction ................................................................................................................................... 299  
12.2 Relaying......................................................................................................................................... 299  
12.3 Deliver to File................................................................................................................................ 299  
12.4 Discarding ..................................................................................................................................... 300  
12.5 Delivering to local application (pipe)............................................................................................ 300  
12.6 Processing Asynchronous (Remote) Bounces and remote status reports ...................................... 301  
12.7 Processing Feedback Loop Emails................................................................................................ 303  
12.8 Tracking a campaign in PowerMTA with a JobID........................................................................ 305  
A. Deprecated APIs .................................................................................................................................. 305  
A.1. Submission API .............................................................................................................................. 306  
A.1.1. Using the C Submission API.................................................................................................. 306  
A.1.2. Function Reference ................................................................................................................ 306  
A.2. Perl Submission API....................................................................................................................... 313  
A.2.1. Function Reference ................................................................................................................ 313  
Acknowledgments..................................................................................................................................... 319  
DIRECTIVES INDEX ............................................................................................................................. 322  
7
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
1. Introduction  
1.1 General Description and Basic Functionality  
PowerMTA is specialized, high performance Message Transfer Agent (MTA) software  
that intelligently and efficiently delivers large volumes of e-mail, allowing for maximum  
delivery and response. While all-purpose MTAs in use today perform a whole variety of  
tasks including delivering e-mail, these general solutions fall short both in regards to  
scalability and relevant feature sets, negatively affecting delivery rates and subsequent  
ROI. In contrast, PowerMTA was developed for this particular task, helping legitimate,  
permission based e-mail marketers, publishers, and service providers overcome the  
business and technology challenges of e-mail message delivery.  
PowerMTA's basic functionality consists of receiving inbound or outbound messages via  
either standard e-mail protocols (SMTP) or programming interfaces, routing them based  
on either name services (DNS) or pre-configured information and delivering them using  
SMTP or locally to a program.  
1.2 Minimum Requirements  
PowerMTA currently runs on:  
Microsoft Windows 2003/2008/7 Intel and compatible processors  
Red Hat Enterprise Linux 4.4 or later on Intel and compatible processors (S.u.S.E.  
Linux support available upon request) (32 and 64 bit)  
Sun Solaris 8 or later on SPARC processors  
Prerequisites:  
a name server (DNS), not necessarily on the same host,  
a static IP address and a domain name,  
a license activation key (LAK),  
minimum hardware requirements, depending on the size of the workload and mail  
queues, and the desired throughput rate.  
Contact Port25 if you need hardware recommendations for your specific workload and  
throughput requirements.  
1.3 Supported interfaces  
PowerMTA supports the following submission and delivery interfaces:  
Submission via standard (extended) SMTP  
Submission via C/C++ API  
Submission via .NET API  
Submission via Perl API  
Submission via Java API  
8
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
       
Submission via "pickup" directory  
Delivery via standard (extended) SMTP  
Delivery to a local program  
and will be supporting others in the future. Unless otherwise noted, these interfaces are  
available on all supported operating systems. You will find detailed information about the  
submission APIs in Chapter 7. Sample applications for the various APIs are also  
distributed along with PowerMTA.  
1.4 Monitoring/Management Tools Summary  
PowerMTA was designed to require only minimal configuration and very little  
management. However, for those who want to actively monitor and manage, a variety of  
flexible tools are available to do just that, both on a manual or automated basis. Full  
details and examples are provided in this Guide, but here is a quick list of the resources  
available:  
a built-in web-based monitor that allows you to view in real time what is currently  
taking place within the mailer. This monitor also includes a view and top level  
break down of the current mail queues, a view and breakdown of each  
VirtualMTA queue, a view of each job/campaign in the queue, as well as the last  
error received for each domain;  
a command line tool supporting a variety of monitoring and management  
commands, with three output formats (text, XML and DOM-style), which allow  
for easy integration into existing monitoring infrastructures or custom parsing and  
monitoring applications;  
detailed logging, both for incoming and outgoing connections, configurable both  
globally and for specific destination domains;  
detailed accounting data in XML format on each successful and unsuccessful  
transfer/delivery  
that  
can  
be  
post  
processed  
for  
delivery  
verification/accountability, for performance and throughput analysis, etc.  
a powerful accounting file search and reporting tool, allowing one to search for  
records in the accounting file and then to produce a custom output based on  
specific fields in the matching records.  
an accounting statistics application for extracting the most commonly needed  
information for monitoring and capacity planning.  
9
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
2. PowerMTA Installation  
2.1 Installing on Microsoft Windows 2003/2008/7  
How to install:  
1. Download the kit;  
2. Log in as Administrator;  
3. Run the install file (for example, by double-clicking on it from the Windows  
Explorer);  
4. If you are installing PowerMTA for the first time or upgrading from a different  
version, copy the license key received from Port25 to a file named license.dat  
in the directory where PowerMTA was installed (e.g., C:\pmta\license.dat).  
Please ensure that the file is stored as in ASCII, not in Unicode;  
5. Check that the configuration (e.g., C:\pmta\config.dat) suits your needs; the  
file can be edited with any ASCII-editor such as Notepad. See Section 2.4 for  
details;  
6. Start the mailer from the Services item in the Control Panel or by typing net  
start pmtain a Command Prompt window;  
7. If you are upgrading from a v1.0 or v1.1 beta release and are using the C/C++  
submission API, recompile and relink your applications;  
8. If you intend to use the Perl API, install or update it from a command prompt  
window (possibly changing the path first) Currently only PERL 5.6 is supported:  
ppm install --location=C:\pmta\api Port25-Submitter  
and  
ppm install --location=C:\pmta\api Port25-Accounter  
9. If you intend to use the Java API, include pmta.jar in your classpath. You may  
want to extract the JavaDoc API documentation from pmtajavadoc.zip. If you  
want to use PowerMTA with Sun's JavaMail API, install the provided  
javamail.providers file according to your system configuration. See the  
JavaMail documentation for details.  
10. If you have an anti-virus and/or indexing service, they should not scan or handle  
the spool files, accounting files, or log files to prevent file locking issues with  
PowerMTA.  
2.2 Installing on Linux  
10  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
How to install:  
1. Download the kit;  
2. Log in as root;  
3. If installing for the first time, optionally create a group called pmta. Membership  
to this group authorizes non-root users to execute PowerMTA commands and  
access the submission APIs. The group is created automatically by the installation  
procedures, but creating it manually allows you to also choose its numeric ID;  
4. PowerMTA is built to work with a kernel as delivered with the Red Hat  
distributions. We do not encourage using a custom-built kernel. However, if using  
a custom-built kernel, please check Section 2.2.1 for how to generate a kernel  
with increased system limits;  
5. If Goodmail was installed, remove it with:  
# rpm –e PowerMTA-goodmail  
6. Install the package (substituting the file name as appropriate) ;  
# rpm -Uvh PowerMTA-4.*.rpm  
Or on Debian:  
# dpkg -i PowerMTA-4.*.deb  
7. If installing for the first time or upgrading from a different version of PowerMTA,  
copy the license key received from Port25;  
# cp mykey.txt /etc/pmta/license  
8. Check that the initial configuration (/etc/pmta/config) suits your needs, as  
described in Section 2.4;  
9. Start the mailer (only necessary immediately after the install: it will be started  
automatically upon system startup);  
# /etc/rc.d/init.d/pmta start  
10. If you are upgrading from a v1.0 or v1.1 beta release and are using the C/C++  
submission API, recompile and relink your applications;  
11. If you intend to use the Perl Submission install or update it from /opt/pmta/api.  
The Submitter package is distributed in the standard CPAN format, so you will  
need to unpack, compile and install as follows.  
# cd /opt/pmta/api  
# tar -xzf Port25-Submitter-1.5.tar.gz  
# cd Port25-Submitter-1.5  
# perl Makefile.PL  
# make test  
# make install  
11  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
12. If you intend to use the Java API, include pmta.jar in your classpath. You may  
want to extract the JavaDoc API documentation from pmtajavadoc.zip. If you  
want to use PowerMTA with Sun's JavaMail API, install the provided  
javamail.providers file according to your system configuration. See the  
JavaMail documentation for details.  
2.2.1 System Limits on Linux  
In many Linux kernels distributed from ftp://ftp.kernel.org the maximum number of  
processes per user (i.e., the ulimit -u limit) is 256, not allowing PowerMTA to start  
more than that many threads/connections. Additionally, the total number of processes in  
the system is limited to 512, so that if 256 are started by PowerMTA, you may find  
yourself unable to run any more commands.  
To overcome these limitations, you can either use a kernel that has higher limits (e.g.,  
Red Hat Linux 6.2 or later), or modify certain system constants and rebuild your kernel.  
If you prefer changing your current kernel,  
1. edit the file include/linux/tasks.hand modify the constants  
o NR_TASKS(total maximum number of processes) to, for example, 2560  
2. MAX_TASKS_PER_USER(maximum processes per user) to, for example, 2048  
3. rebuild and install your kernel as usual  
4. reboot  
5. verify that ulimit -udisplays the new limit  
2.3 Installing on Solaris  
How to install:  
1. download the kit;  
2. log in as root;  
3. if installing for the first time, please see Section 2.3.1 for how to increase your  
system's limits;  
4. make sure that you have gzip and gnu tar installed. If they are not, you can  
download these from a site like ftp://sunsite.unc.edu/pub/packages/solaris/;  
5. extract the package (substituting the file name as appropriate);  
# tar -xjf PowerMTA-4.*.sparc.solaris.pkg.tar.gz  
6. if upgrading, remove the previous installation (your configuration will be  
retained);  
12  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
# pkgrm PT25pmta  
7. install the package;  
# pkgadd -d . PT25pmta  
8. if installing for the first time or upgrading from a different version of PowerMTA,  
copy the license key received from Port25;  
# cp mykey.txt /etc/pmta/license  
9. check that the initial configuration (/etc/pmta/config) suits your needs, as  
described in Section 2.4;  
10. start the mailer (only necessary immediately after the install; it will be started  
automatically upon system startup);  
# /etc/init.d/pmta start  
11. if you are upgrading from a v1.0 or v1.1 beta release and are using the C/C++  
submission API, recompile and relink your applications;  
12. If you intend to use the Perl Submission install or update it from  
/opt/PT25pmta/api. The Submitter package is distributed in the standard CPAN  
format, so you will need to unpack, compile and install as follows.  
# cd /opt/PT25pmta/api  
# tar -xzf Port25-Submitter-1.5.tar.gz  
# cd Port25-Submitter-1.5  
# perl Makefile.PL  
# make test  
# make install  
13. if you intend to use the Java API, include pmta.jar in your classpath. You may  
want to extract the JavaDoc API documentation from pmtajavadoc.zip. If you  
want to use PowerMTA with Sun's JavaMail API, install the provided  
javamail.providers file according to your system configuration. See the  
JavaMail documentation for details.  
2.3.1 System Limits on Solaris  
The default SunOS limit on the number of files a process can simultaneously open  
(maximum file descriptors, ulimit -uH) is often too low for PowerMTA. There are  
actually two limits available: a hard limit which processes cannot exceed, and a soft limit  
which really just defines the default maximum number of files, but which can be raised  
up to the hard limit.  
While the exact maximum required depends on the number of connections you will be  
simultaneously running, a hard limit of 4096 should suffice for most installations.  
13  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Unfortunately, many programs assume that at most 1024 file descriptors are available and  
may misbehave or crash if allowed that many files per default. So it is also necessary to  
define the "soft" limit to a more conservative value. This will not disturb PowerMTA, as  
it will automatically raise its soft limit to the hard limit during startup.  
In order to change these limits:  
1. For Solaris version 8 and earlier, edit /etc/system, adding the lines  
set rlim_fd_max=4096  
set rlim_fd_cur=1024  
For Solaris version 9 and later, edit /etc/system, adding the following lines if  
the default is not already set to these values. rlim_fd_max can be increased if  
needed.  
set rlim_fd_max=65536  
set rlim_fd_cur=1024  
2. reboot  
You can then verify that ulimit -nand ulimit -nHdisplay the new limits.  
Note: under certain circumstances (namely, when a program raises its soft limit but still  
assumes its hard limit will not be above 1024), programs may still misbehave despite the  
lower soft limit. In such cases, adding a statement like  
ulimit -uH 1024  
to such program's start scripts so that the hard limit is lowered to 1024 should solve the  
problem.  
2.4 Initial Configuration  
There are only two things that must be manually defined in the configuration file, in  
addition to the supplied default entries, in order to have PowerMTA up and running: the  
postmaster address(es) and the relaying control configuration.  
Besides being the traditional address for which external parties can reach the maintainer  
of the mail server, the postmaster address is used by PowerMTA and its watchdog  
monitoring facility, pmtawatch, to send crash reports and other information to upon  
successful automatic restart of the mailer (if it crashes).  
For security reasons, PowerMTA does not allow external relaying by default; the default  
configuration only allows messages to be sumitted from the local 127.0.0.1 IP address. In  
order to submit messages for delivery from a different host, you will need to enter its IP  
14  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
address(es) into the configuration file by creating one or more source entries and  
specifying the always-allow-relayingdirective.  
Note that relay-domain and relay-address directives in the configuration file are  
really only useful when PowerMTA is used to handle inbound traffic. That allows you to  
specify the domains in messages which PowerMTA is to accept from any sources. When  
configuring PowerMTA for outbound, you want it to accept e-mail from your feeders for  
all domains, by using always-allow-relaying.  
See Chapter 3 for detailed information on the configuration file.  
2.4.1 IPv6  
PowerMTA now supports IPv6. This requires an OS that supports IPv6 and an IPv6  
address. Other than that, the IPv6 address can be used in place of an IPv4 address in the  
configuration file.  
Examples:  
smtp-listener [FE80::0202:B3FF:FE1E:8329:25]:25  
<domain test.port25.com>  
route [2001:db8::1]:26  
</domain>  
<source fe80::202:b3ff:fe1e:1839>  
smtp-service yes  
</source>  
http-access ::1 admin  
2.5 Uninstalling  
On each platform PowerMTA is installed with the platform's standard packaging  
software. You can uninstall PowerMTA using the platform's existing uninstall option:  
On Windows NT/2000, open the Control Panel, open Add/Remove Programs,  
select the PowerMTA item, and click on Add/Remove. After confirming that you  
would like to proceed, that will initiate the uninstall process.  
On Linux, log in as root and execute rpm -e PowerMTA  
On Solaris, log in as root and execute pkgrm PT25pmta  
Any configuration, logging, accounting and message files found in PowerMTA's  
directories will not be automatically removed — so neither will the directories  
themselves. On Linux and Solaris, the uninstall software will display a list of the  
remaining files and the commands you need to execute to remove them. On Windows  
15  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
NT/2000, you can simply remove the complete directory tree onto which you had  
installed PowerMTA.  
16  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3. PowerMTA Configuration  
3.1 Working with the Configuration File  
PowerMTA's configuration file is a straightforward ASCII text file that can be read and  
modified with most text editors (e.g., Notepad, vi, emacs). Settings are entered one per  
line and are formed by a keyword on the left identifying a directive and a value on the  
right, as in the example below:  
smtp-port 2525 # use alternate SMTP port  
Certain directives, like those applying to a specific destination domain, are grouped based  
on what they apply to:  
<domain test.port25.com>  
route [127.0.0.1]:11111  
log-commands yes  
# 'test' host  
</domain>  
As indicated in the examples above, comments can be introduced by prefixing the  
comment with a hash mark "#". Like other file formats using the hash mark for  
comments, PowerMTA ignores the "#" and any characters following it until the end of  
the line.  
PowerMTA reads the configuration file upon startup. After making changes to the  
configuration file, you must thus either re-start it or execute the pmta reloadcommand.  
Because it is more efficient and does not cause an interruption in service, in general the  
reload command is preferrable to re-starting PowerMTA. However, some directives  
such as the location of the spool directories cannot be reloaded dynamically and require a  
restart. Unless otherwise noted in the descriptions below, you can assume the directives  
to be dynamically reloadable.  
PowerMTA supports the ability to remotely modify/upload a configuration file via the  
web UI (and thus via HTTP). To push the configuration programmatically, one needs to  
issue a HTTP POST, passing the configuration file in the field named "file" to the URL  
http://127.0.0.1:8080/editConfig. One also needs to be authorized for "admin" access via  
the http-access directive.  
3.2 Configuration Directives  
The following sections describe the various configuration directives available, grouped  
by function. Each description includes a little table specifying the directive's scope, type,  
attributes and default.  
17  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
3.2.1 Directive “Scope” Defined  
A directive's scope indicates where in the configuration file it can be specified.  
3.2.2 Directive “Type” defined  
A directive's type indicates the kind of values accepted. They are as follows:  
boolean  
A boolean directive, accepting the values yes, true, noand false.  
number  
A number. The valid ranges depend on how the number is used. For example, port  
numbers must be between 0 and 65535 and may be subject to further limitations  
in range by the operating system.  
file name  
A file's name. Unless otherwise noted, should always be an absolute file name,  
either beginning at the root (on Unix) or at the drive name (Windows NT/2000).  
directory name  
A directory's name. Unless otherwise noted, should always be an absolute  
specification, either beginning at the root (on Unix) or at the drive name  
(Windows NT/2000).  
time interval  
A sequence like 1d2h3m4s, meaning one day, two hours, three minutes and four  
seconds. Parts of the specification can be omitted, like in 4d12h, which stands for  
four days and twelve hours.  
IP address  
An IP address in dotted decimal notation, like 10.0.0.1.  
IP address list  
The directive builds a list of IP addresses. Each directive specifies an additional  
IP address that is appended to the list.  
e-mail address  
An e-mail address, like support@port25.com, not including a free form name  
like "John E. Doe" or <>characters, etc.  
string  
A string of characters. If the string contains any spaces or tabs, it should be  
enclosed in double quotes ("").  
directory name list  
The directive builds a list of directory names. Each directive adds a directory  
name to the end of the directory list. Unless otherwise noted, should always be an  
absolute specification, either beginning at the root (on Unix) or at the drive name  
(Windows NT/2000).  
IP address list  
The directive builds a list of IP address ranges. This list is then used by  
PowerMTA to match IP addresses. For example, when deciding whether to grant  
access to the web-based monitor, PowerMTA scans the list built with the http-  
accessdirective.  
18  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
Each directive specifies either an IP address in dotted decimal notation (like  
10.0.0.1), or a range of IP addresses in CIDR notation (like 10.0.0.0/8). CIDR  
specifications are formed by an IP address prefix and by the number of significant  
bits within the 32-bit number formed by the prefix. In the example above, only the  
first eight bits (the 10 portion) are significant, so any IP addresses starting with  
10.would match.  
domain  
The directive builds a list domain wildcards. This list is then used by PowerMTA  
to match domain names.  
Domains can be specified in one of the following formats:  
*
Matches all domains.  
domain  
A single, fully qualified domain name. Matches that specific domain only.  
*.domain  
Matches any subdomains of domain, but not the domain itself.  
[*.]domain  
Matches domain as well as its subdomains.  
[ip/mask]  
Matches domains in the dotted decimal format, like [127.0.0.1]. The  
actual IP address in the domain must match the given CIDR specification  
(ip prefix and mask number of significant bits). [0/0] matches all  
domains in dotted decimal format.  
3.2.3 Directive “Attribute” defined  
A directive's attributes indicate  
required/optional  
whether a directive must be specified in the configuration file  
obsolete  
whether a directive is obsolete and should no longer be used  
non reloadable  
whether a directive can be reloaded dynamically by using the pmta reload  
command. If a directive is non reloadable, PowerMTA must be restarted before  
any changes to it become active.  
3.2.4 Directive “Default” defined  
A directive's default is simply the value or behavior when the directive is not specified in  
the configuration file. Please note that the initial configuration may differ from the  
directive's default.  
19  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
3.2.5 <global> Directives Defined  
The directive is "global" and affects PowerMTA as a whole.  
3.2.6 <domain> Directives Defined  
The directive affects items (like e-mail queued, outgoing connections, etc.) related  
to the specified domain name. The directive should be specified within a  
<domain> entry, like in  
<domain *.port25.com>  
bounce-after 6d  
</domain>  
Domains can be specified in one of the following formats:  
*
Matches all domains.  
domain  
A single, fully qualified domain name. Matches that specific domain only.  
*.domain  
Matches any subdomains of domain, but not the domain itself.  
[*.]domain  
Matches domain as well as its subdomains.  
[ip/mask]  
Matches domains in the dotted decimal format, like [127.0.0.1]. The actual IP  
address in the domain must match the given CIDR specification (ip prefix and  
mask number of significant bits). [0/0] matches all domains in dotted decimal  
format.  
Domain directives may be added in any order to the configuration file. When  
PowerMTA needs to determine what parameters to use for a specific domain, it  
uses the best matching (most specific) entry, regardless of the order domain  
directives are placed into the configuration file.  
<domain discard.port25.com> # matches 'discard' only  
...  
</domain>  
<domain *.port25.com>  
# matches subdomains of port25.com  
...  
</domain>  
<domain [*.]port25.com> # matches port25.com and all subdomains  
...  
</domain>  
<domain *>  
...  
# matches all domains  
</domain>  
When PowerMTA reads the configuration file, it merges settings for related  
domains from more general to more specific domains, so you can provide defaults  
for all domains by specifying them for the "*" pseudo-domain or for a specific  
site by specifying them for the toplevel domain for the site.  
20  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
In the following example, commands will be logged for all proper subdomains of  
port25.com (but not for port25.com itself) and undelivered messages to any  
address at port25.com will bounce after four days, except for messages to  
discard.port25.com, which will bounce after one hour.  
<domain discard.port25.com>  
bounce-after 1h  
</domain>  
<domain *.port25.com>  
log-commands yes  
</domain>  
<domain [*.]port25.com>  
bounce-after 4d  
</domain>  
<domain *>  
bounce-after 6d  
</domain>  
To include domains that have different root domains (e.g. yahoo.com &  
yahoo.co.uk), PowerMTA has the ability to define top level domain macros. To  
use this feature, you would first define a domain macro with the desired list of  
bindings.  
domain-macro topLevel com, de, co.uk  
and then use it in the <domain> tag like.  
<domain aol.$topLevel>  
...settings...  
</domain>  
PowerMTA automatically expands that to aol.com, aol.de, and aol.co.uk. You can  
also use several macros within a <domain>, as in the following:  
domain-macro topLevel com, de, co.uk  
domain-macro aol aol, aim  
<domain $aol.$topLevel>  
...settings...  
</domain>  
This expands to aol.com, aim.org, aol.de, aim.de, aol.co.uk and aim.co.uk.  
You can also use macros within macros:  
domain-macro com com, co.uk, com.br  
domain-macro tld $com, org, net  
21  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
In which case tld expands to com, co.uk, com.br, org and net. Any loops are  
detected and result in an error (which prevents the configuration from being  
reloaded).  
Also, specifically listed domains always take precedence over expanded ones. For  
example, in.  
<domain aol.com>  
max-smtp-out 100  
</domain>  
domain-macro com com, co.uk  
<domain aol.$com>  
max-smtp-out 50  
</domain>  
aol.com would have a limit of 100.  
3.2.7 <source> Directives Defined  
The directive affects incoming SMTP connections from the given source. The  
directive should be specified within a <source>entry, like in  
<source 10.0.0.0/8>  
log-connections yes  
</source>  
Per-source directives can be specified in two ways: by IP address and by name.  
Each <source>entry to be applied by IP address specifies either an IP address in  
dotted decimal notation (like 10.0.0.1), or a range of IP addresses in CIDR  
notation (like 10.0.0.0/8). CIDR specifications are formed by an IP address  
prefix and by the number of significant bits within the 32-bit number formed by  
the prefix. In the example above, only the first eight bits (the 10 portion) are  
significant, so any IP addresses starting with 10.would match.  
A <source> entry to be applied by name specifies its name in the entry, like in  
<source S1>.  
Source entries are scanned sequentially by PowerMTA when a new incoming  
connection request is received. The first matching entry for any directive is used,  
so it is important to enter them in the proper order — from more specific to more  
general, as in the example below:  
22  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
<source 10.0.0.5>  
...  
</source>  
<source 10.0.0.0/8>  
...  
# matches 10.0.0.5 only  
# matches 10.*  
</source>  
<source 0/0>  
...  
# matches all  
</source>  
Note that PowerMTA merges ("inherits") settings in source entries like it does  
for the domain entries, allowing you to provide defaults in a more generic entry  
(such as 0/0). Still, contrary to the domain entries, source entries cannot be  
automatically sorted, which is why you need to specify them in the order you  
wish them used.  
Named entries are used to override the settings obtained based on the source IP  
address. They apply only when specifically requested, like in the source=...  
parameter of the smtp-listenerdirective.  
3.2.8 <source-group> Directives Defined  
The directive affects incoming SMTP connections from the given group of  
<source> tags. The directive allows for specifying certain source configuration  
items whose functionality require them to be grouped by name. The shared  
resources will be defined in the <source-group> tag. To add a <source> to the  
shared resource, specify the name of the <source-group> in the <source> tag.  
An example would look similar to the following:  
<source-group localSources>  
max-smtp-in 10  
reserved-smtp-in 5  
</source-group>  
<source 192.168.0.30>  
smtp-service yes  
always-allow-relaying yes  
source-group localSources  
</source>  
<source 192.168.0.40>  
smtp-service yes  
always-allow-relaying yes  
source-group localSources  
</source>  
Each <source> that defines the source-group directive of the same name will be  
controlled by the settings in the named <source-group>tag.  
23  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
3.2.9 <virtual-mta> Directives Defined  
The directive specifies behavior specific to a "VirtualMTA". VirtualMTA  
directives only apply when that VirtualMTA has been selected through one of the  
supported selection methods. They should be specified in a <virtual-mta>entry,  
like in  
<virtual-mta mta1>  
smtp-source-host 1.2.3.4 mta1.company.com  
<domain *>  
dk-sign yes  
</domain>  
</virtual-mta>  
See Chapter 8 for more information on VirtualMTAs.  
3.2.10 <virtual-mta-pool> Directives Defined  
The directive is valid in a virtual-mta-pool entry. VirtualMTA pools are  
groups of VirtualMTAs. They share the same name space as VirtualMTAs, so that  
you can select a pool instead of a specific VirtualMTA. When you select a  
VirtualMTA pool, the VirtualMTAs in that pool are used in round-robin fashion  
to deliver the message. See Chapter 8 for more information on VirtualMTAs and  
VirtualMTA pools.  
3.2.11 <pattern-list> Directives Defined  
The directive adds a regular expression pattern to a list of patterns. Such patterns  
can be used to select a VirtualMTA based on the message's originator. It should  
be entered in a <pattern-list>entry, like in  
<pattern-list myList>  
mail-from /^newsletter/  
mail-from /^specials/  
virtual-mta=newsletters  
virtual-mta=specials  
rcpt-to /^stud.*@somesite.com$/ virtual-mta=students  
rcpt-to /password-reset@customer.com/ recipient-priority=60  
rcpt-to /special@customer.com/ virtual-mta=high, recipient-priority=60  
</pattern-list>  
Conditional AND/OR style patterns can be defined. See Chapter 8 for more  
information on selecting VirtualMTAs. Section 3.2.16 describes pattern lists in  
greater detail.  
24  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
3.2.12 <smtp-pattern-list> Directives Defined  
The directive adds a regular expression pattern to a list of patterns. Such patterns  
can be used to have PowerMTA take certain actions based on the SMTP replies  
received from the remote mailer. It should be entered in a <smtp-pattern-list>  
entry, like in  
<smtp-pattern-list myList>  
reply /blocked/ mode=backoff  
reply /permanently deferred/ bounce-queue  
reply /too many connections/ skip-mx  
reply /account over quota/ bounce-rcpt  
</smtp-pattern-list>  
Section 3.2.36 describes SMTP pattern lists in greater detail.  
3.2.13 <bounce-category-patterns> Directives  
Defined  
This directive makes the bounce categories used in CSV accounting files and the  
X-PowerMTA-BounceCategory DSN field customizable (binary files still use the  
built-in categories). A customer can specify the tag in the configuration file, in  
which case the patterns specified there take precedence over those defined in  
config-defaults file. The data in the <bounce-category-patterns> tag consist  
of two fields. The first field is the SMTP response on which to match, and the  
second field is the name of the category to be used. Custom category names are  
allowed. It should be entered in a <bounce-category-patterns>entry, like in  
<bounce-category-patterns>  
/spam/ spam-related  
/no longer (valid|available)/ bad-mailbox  
/mailbox +(is +)?full/ quota-issues  
/banned/ policy-related  
</bounce-category-patterns>  
<bounce-category-patterns> uses pattern matching in the same method as  
does <pattern-list>. Section 3.2.16 describes SMTP pattern lists and pattern  
matching in greater detail.  
3.2.14 <acct-file> Directives Defined  
These directives only apply to the CSV accounting file. The directive specifies  
behavior specific to the CSV accounting file. It should be used in a manner  
similar to the following:  
<acct-file log\acct.csv>  
move-interval 5m  
max-size 50M # MB  
sync no  
</acct-file>  
25  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
See Chapter 11 for more information on the accounting file.  
3.2.15 <smtp-user> Directives Defined  
The directive adds the abilty to specify a given user who should be able allowed  
to send email, regardless of the IP from which the mail is sent, to PowerMTA for  
relaying. The directive should be used once per user and reference a general  
source tag that controls the various directives to control the messages. It should  
be entered in a <smtp-user>entry, like in  
<smtp-user jsmith>  
password MyPassword  
source {auth}  
</smtp-user>  
<source {auth}>  
always-allow-relaying yes # allow feeding for defined users  
process-x-virtual-mta yes # allow selection of a VirtualMTA  
max-message-size 0  
smtp-service yes  
require-auth true  
# 0 implies no cap, in bytes  
# allow SMTP service  
</source>  
<source 0/0>  
allow-unencrypted-plain-auth yes  
</source>  
Section 10.2.2 describes smtp-user in greater detail.  
As a note, <source {auth}> is reserved, and if no source for <smtp-user> is  
specified, <source {auth}> will be used. Any other non-reserved named source  
may be used for <smtp-user>.  
26  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
On a Linux the system accounts may be used.  
To do so configure the  
“authentication-method system” directive similar to the following:  
<smtp-user jsmith>  
authentication-method system  
source {auth}  
</smtp-user>  
<source {auth}>  
always-allow-relaying yes # allow feeding for defined users  
process-x-virtual-mta yes # allow selection of a VirtualMTA  
max-message-size 0  
smtp-service yes  
require-auth true  
# 0 implies no cap, in bytes  
# allow SMTP service  
</source>  
<source 0/0>  
allow-unencrypted-plain-auth yes  
</source>  
27  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3.2.16 <spool> Directives Defined  
The directive allows one to specifiy the location of the spool file. New spools  
may be activated with a reload of PowerMTA. Deactivating a <spool> requires a  
restart of PowerMTA.  
<spool /var/spool/pmta>  
delete-file-holders yes  
deliver-only yes  
</spool>  
<spool C:\pmta\spool>  
</spool>  
3.2.17 <bounce-processor> Directives Defined  
The directive allows for using the bounce processor in PowerMTA. If configured,  
PowerMTA will look for bounce emails when processing incoming messages.  
<bounce-processor>  
deliver-email yes  
# default: no  
forward-unmatched-to auto-feedback@port25.com  
forward-errors-to auto-feedback@port25.com  
<address-list>  
domain domain.to.filter  
address /regex@domain.to.filter/  
# whole domain  
# regex  
</address-list>  
</bounce-processor>  
See Section 12.1.6 for more detail on the <bounce-processor> directives.  
3.2.18 <feedback-loop-processor> Directives  
Defined  
The directive allows for using the feedback loop processor in PowerMTA. If  
configured, PowerMTA will look for feedback loop emails when processing  
incoming messages.  
<feedback-loop-processor>  
deliver-email no  
forward-unmatched-to auto-feedback@port25.com  
forward-errors-to auto-feedback@port25.com  
<address-list>  
address /fbl@mydomain.com/  
</address-list>  
</feedback-loop-processor>  
See Section 12.1.7 for more detail on the <feedback-loop-processor> directives.  
28  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
3.2.19 <address-list> Directives Defined  
The directive defines the address or patterns to match on when using <bounce-  
processor> or <feedback-loop-processor>. See Section 12.1.6 for more detail on  
the <bounce-processor> directives. See Section 12.1.7 for more detail on the  
<feedback-loop-processor> directives.  
3.2.20 General Directives  
postmaster  
Scope:  
Type:  
global  
e-mail address  
Attributes: optional  
Default:  
none  
Specifies an e-mail address for the person responsible for PowerMTA's operation.  
This should always be specified because it is used by the internal watchdog  
facility for crash and LAK expiry notifications. Messages sent to the local  
postmaster and abuse addresses are also by default forwarded to the given  
addresses. You can specify more than one address by entering postmaster  
multiple times.  
Example:  
postmaster you@your.domain  
postmaster you@your.domain.at.home  
29  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
3.2.21 Message Spool Directives  
spool  
Scope:  
Type:  
global  
directory name list  
Attributes: required, non reloadable  
Default:  
none  
Deprecated, use <spool> tag and directives.  
Specifies an additional directory for the message spool. The message spool is  
where PowerMTA stores the message files while queued for delivery. At least one  
spoolentry is required. Additional entries can be added for greater performance,  
for example by distributing the I/O load over several physical disks.  
Example: (Unix)  
# distribute PowerMTA's spool I/O load away from the system  
disk  
# and over to disks 2 - 4  
spool /dsk2/pmta-spool  
spool /dsk3/pmta-spool  
spool /dsk4/pmta-spool  
Example using <spool> tag: (Unix)  
<spool /dsk2/pmta-spool>  
</spool>  
<spool /dsk3/pmta-spool>  
</spool>  
<spool /dsk4/pmta-spool>  
</spool>  
delete-file-holders  
Scope:  
spool  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Determines whether PowerMTA should delete any message holders in the spool  
directory after a message has been delivered. Will remove 0kb files at the cost of  
some HDD I/O.  
30  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
deliver-only  
Scope:  
spool  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Determines whether PowerMTA should stop adding new message files to a spool  
location. Messages from the spool location will however continue to be delivered.  
This can be usefull if a spool was added from another server for recovery, but  
only for purposes of delivery.  
Note: For a spool directory defined with the deprecated spool directive, 'deliver-  
only' and 'delete-file-holders' will default to false, and cannot be changed.  
spool-delete-corrupted  
Scope:  
global  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Determines whether PowerMTA should delete any message files in the spool  
found to contain encoding errors, such as those caused by disk data corruption.  
spool-max-files  
Scope:  
Type:  
global  
autoor number  
Attributes: deprecated, optional, non reloadable  
Default:  
auto  
This directive is currently an alias for spool-max-recipients. Please use  
spool-max-recipientsinstead.  
min-free-space  
Scope:  
Type:  
spool  
{n{B|K|M|G|T}}  
Attributes: optional  
Default:  
0
If the number of bytes available (to non-root users) falls below what this directive  
specifies (in MB), PowerMTA stops accepting email. When available disk space  
increases above that level, messages are accepted again.  
31  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
spool-max-recipients  
Scope:  
Type:  
global  
autoor number  
Attributes: optional, non reloadable  
Default:  
auto  
Specifies the maximum number of recipients to allow in the spool, to help prevent  
overwhelming PowerMTA with more messages than it has the resources to  
handle. When this limit is reached, feeding new messages into PowerMTA fails  
with a transient error message. If set to auto, the maximum number is determined  
automatically based on system resources (currently only on RAM, but this may  
change in the future).  
3.2.22 Relaying Control Directives  
always-allow-relaying  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether SMTP senders from the given source should be allowed to  
relay e-mail through PowerMTA, even if the recipients are not for one of the  
relay-domains. Typically you should enable this in the source entries of  
"internal" hosts feeding PowerMTA through SMTP.  
32  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
relay-domain  
Scope:  
global  
Type:  
domain  
Attributes: optional  
Default:  
local domains  
Domain name (and domain wildcards) for which PowerMTA will accept e-mail.  
Any host is allowed to relay e-mail for these domains, independent of its source  
IP address. Directive may be specified more than once.  
This directive is mostly useful for handling inbound e-mail. When setting up  
PowerMTA for relaying inbound e-mail to some other host, you should enter the  
corresponding domain name(s) into the relay domains list. Conversely, if in your  
installation PowerMTA is handling outbound e-mail only, there is no need to  
configure any relay domains.  
Example:  
# route e-mail for other.host to 10.0.0.5:1025  
<domain other.host>  
route [10.0.0.5]:1025  
</domain>  
# allow relaying for other.host  
relay-domain other.host  
relay-address  
Scope:  
Type:  
global  
string  
Attributes: optional  
Default:  
none  
Email address for which PowerMTA will accept e-mail. Any valid email is  
allowed to relay e-mail for independent of its source IP address. Directive may  
be specified more than once.  
This directive is mostly useful for handling inbound e-mail. When setting up  
PowerMTA for relaying inbound e-mail to some other host.. Conversely, if in  
your installation PowerMTA is handling outbound e-mail only, there is no need to  
configure any relay addresses.  
Example:  
relay-address bounce@bounce.yourdomain.com  
33  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
relay-debug  
Scope:  
global  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies that relaying control is to be performed in "debugging" mode. Normally,  
recipients to which relaying is not allowed are rejected with persistent (5XX)  
SMTP error codes, causing immediate bounces. In debugging mode, a transient  
(4XX) error is returned instead to the sending mailer, allowing it to continue  
trying to deliver to that recipient. This directive comes handy when making  
changes to the relaying control configuration since it gives you a chance to review  
the log for any unintended rejections and correct the configuration before  
messages are bounced.  
deliver-email  
Scope:  
Type:  
bounce-processor, feedback-loop-processor  
boolean  
Attributes: optional  
Default:  
no  
Determines whether the emails processed continue on to delivery (emails that  
PowerMTA could not understand are always passed on to delivery).  
forward-unmatched-to  
Scope:  
bounce-processor, feedback-loop-processor  
Type:  
email address  
Attributes: optional  
Default:  
false  
This directive allows for forwarding messages unmatched by the bounce  
processor or feedback loop processor, to facilitate collecting emails that matched  
the defined pattern or email, but were not able to be determined as a bounce or  
feedback loop email.  
34  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
forward-errors-to  
Scope:  
bounce-processor, feedback-loop-processor  
email address  
Type:  
Attributes: optional  
Default:  
false  
This directive allows for forwarding messages unmatched by the bounce  
processor or feedback loop processor, to facilitate collecting emails that matched  
the defined pattern or email, but were not able to be determined as a bounce or  
feedback loop email.  
address  
Scope:  
Type:  
address-list  
string, email address  
Attributes: optional  
Default:  
false  
This directive takes a regular expression (delimited by //) to be matched against  
the entire RCPT TO email address. If the pattern is matched, the message is  
passed to the bounce or feedback loop processor. See Section 12.1.6 for more  
detail on the <bounce-processor> directives. See Section 12.1.7 for more detail  
on the <feedback-loop-processor> directives.  
domain  
Scope:  
Type:  
address-list  
string, domain  
Attributes: optional  
Default:  
false  
This directive takes a regular expression (delimited by //) to be matched against  
the domain portion of the RCPT TO email address. If the pattern is matched, the  
message is passed to the bounce or feedback loop processor. See Section 12.1.6  
for more detail on the <bounce-processor> directives. See Section 12.1.7 for  
more detail on the <feedback-loop-processor> directives.  
35  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3.2.23 SMTP Service Directives  
add-date-header  
Scope:  
Type:  
source  
{no|yes|override}  
Attributes: optional  
Default:  
no  
Specifies whether PowerMTA should add a Date header if missing. If a Date  
header is present, it is not overridden unless using the override parameter.  
Note: automatic adding of the Date header is not supported for mailmerge  
messages. When submitting mailmerge messages, you can use the *datevariable  
to easily accomplish the same.  
date-header-time  
Scope:  
Type:  
source  
{reception|delivery}  
Attributes: optional  
Default:  
reception  
Specifies whether PowerMTA should set the Dateheader to the time the message  
was received and queued for delivery, or the time the message was actually  
delivered. The directive add-date-header needs to be set to yes or override when  
using this directive.  
bcc  
Scope:  
Type:  
source  
sting  
Attributes: optional  
Default:  
This directive takes an email address as a value, and if set, causes each message  
received from that source to be BCC'ed to the given email address. This can be  
used for creating a copy of every message for archival purposes.  
36  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
add-message-id-header  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should add a Message-Id header if missing. If a  
Message-Idheader is present, it is not overridden.  
add-received-header  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether PowerMTA should add a Received header upon reception of  
an email.  
run-as-root  
Scope:  
Type:  
global  
boolean  
Attributes: optional, non reloadable  
Default:  
true  
Specifies whether PowerMTA should run as root or as user pmta. Only works on  
non-Windows systems.  
allow-auth  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether PowerMTA should allow usage of the AUTHSMTP command.  
37  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
remove-header  
Scope:  
source, domain  
string  
Type:  
Attributes: optional  
Default:  
Specifies a header that PowerMTA should remove from the incoming or outgoing  
message. The directive takes a comma separated list of headers if there is more  
than one header to be removed. The header is removed at delivery, not when the  
message is queued to disk.  
The directive may be used in a <source> or  
<domain>, but is not required to be defined in both. To indicate no header is to  
be removed use “” (only needed when overriding an inherited setting).  
Example:  
<source 127.0.0.1>  
remove-header nameOfYourCustomHeader,nameOfOtherHeader  
</source>  
<domain example.com>  
remove-header nameOfYourCustomHeader,nameOfOtherHeader  
</domain>  
<domain *>  
remove-header “”  
</domain>  
require-auth  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Allows for requiring authentication before any emails are received via SMTP  
(local or not).  
allow-mailmerge  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should allow usage of the mailmerge SMTP  
extensions from the given source.  
38  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
allow-unencrypted-plain-auth  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should allow usage of the PLAIN SASL  
authentication mechanism in unencrypted connections (PowerMTA does not  
currently support encryption of connections).  
allow-starttls  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
no  
This directive allows for using server-side STARTTLS.  
require-starttls-before-auth  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
no  
Allows for requiring STARTTLS before any AUTH commands are issued.  
smtp-server-tls-certificate  
Scope:  
Type:  
global  
string  
Attributes: optional  
Default:  
Allows for setting the file and password to be used for server-side STARTTLS.  
Takes a file name and the certificate's password as arguments. See  
http://www.openssl.org/ for information on creating certificates.  
Example:  
smtp-server-tls-certificate /etc/pmta/yourcert.pem Password  
39  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
password  
Scope:  
Type:  
smtp-user  
string  
Attributes: optional  
Default:  
Specifies the password for the defined user in <smtp-user>..  
authentication-method  
Scope:  
smtp-user  
Type:  
system  
Attributes: optional  
Default:  
Specifies the corresponding Linux user account should be used for authentication.  
source  
Scope:  
Type:  
smtp-user  
string  
Attributes: optional  
Default:  
Specifies the <source> to be used for the defined user in <smtp-user>..  
broken-auth-clients  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
true  
Changes the manner in which PowerMTA implements AUTH to allow for some  
email clients, such as Outlook or Outlook Express.  
40  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
verp-default  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
no  
If you enable VERP by setting verp-default to yes or true, PowerMTA will create  
a customized SMTP MAIL FROM address for the message based on the original  
SMTP MAIL FROM address and the RCPT TO addresses in the message. Since  
one can then identify the original RCPT TO address in this new encoded SMTP  
MAIL FROM address, this may make tracking bounces easier for you.  
The format is fixed, and can be see in the following example;  
Original SMTP MAIL FROM: jsmith@example.com  
SMTP RCPT TO: jdoe@yahoo.com  
VERPed SMTP MAIL FROM: jsmith-jdoe=yahoo.com@example.com  
check-domainkeys-inbound  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether to perform a DomainKeys check.  
If the message has  
DomainKeys and it passes, PowerMTA will add an Authentication-Results  
header stating the passing results.  
check-dkim-inbound  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether or not PowerMTA should enable checking DKIM signatures  
on inbound messages. If the message has DKIM and it passes, PowerMTA will  
add an Authentication-Results header stating the passing results.  
41  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
trace-domainkeys-check  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Allows selecting whether the trace data (currently including all the DNS data  
looked up) is included in the Authentication-Results headers for the domainkey  
check.  
trace-dkim-check  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Allows selecting whether the trace data (currently including all the DNS data  
looked up) is included in the Authentication-Results headers for the dkim check.  
trace-pra-check  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Allows selecting whether the trace data (currently including all the DNS data  
looked up) is included in the Authentication-Results headers for the pra check.  
trace-mfrom-check  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Allows selecting whether the trace data (currently including all the DNS data  
looked up) is included in the Authentication-Results headers for the mfrom  
check.  
42  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-errors-per-connection  
Scope:  
Type:  
domain  
number  
Attributes: optional  
Default:  
unlimited  
This directive tells PowerMTA to break a connection after a certain amount of  
recipient level errors. The default is unlimited, meaning that PowerMTA will not  
break a connection due to a number of recipient level errors.  
check-mfrom-outbound  
Scope:  
domain  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should check outbound messages' "mfrom"  
(domain in the MAIL FROM or HELO SMTP commands) for full compliance with  
Sender-ID on outbound messages. If enabled and the check returns a "Pass",  
message delivery continues. If instead returns a "TempError", the message is  
retried. Otherwise, the message bounces.  
To use this feature, you must currently configure a specific smtp-source-host  
(either at the global or VirtualMTA level).  
check-mfrom-inbound  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether to perform an SPF/mfrom check on in bound messages. If the  
message has the mfrom and it passes, PowerMTA will add an Authentication-  
Results header stating the passing results.  
43  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
check-mfrom-inbound-best-guess  
Scope:  
Type:  
source  
text  
Attributes: optional  
Default:  
Specifies a dummy SPF record to use for mfrom checking in case a domain being  
checked does not publish a SPF record.  
check-pra-outbound  
Scope:  
domain  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should check outbound messages' PRA (purported  
responsible address) for full compliance with Sender-ID on outbound messages. If  
enabled and the check returns a "Pass", message delivery continues. If instead  
returns a "TempError", the message is retried. Otherwise, the message bounces.  
To use this feature, you must currently configure a specific smtp-source-host  
(either at the global or VirtualMTA level).  
check-pra-inbound  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether to perform a pra check. If the message has the pra and it  
passes, PowerMTA will add an Authentication-Results header stating the passing  
results.  
check-pra-inbound-best-guess  
Scope:  
Type:  
source  
text  
Attributes: optional  
Default:  
Specifies a dummy PRA record to use for pra checking in case a domain being  
checked does not publish a PRA record.  
44  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
dsn-return-default  
Scope:  
Type:  
source  
full, headersor system  
Attributes: optional  
system  
Default:  
Specifies the default for the DSN RET parameter, i.e., whether the full message  
body or only its headers should be returned in a DSN delivery report. system  
specifies that the system default should be used. This directive is overridden by  
the use of "dsn-format plain-text".  
default-virtual-mta  
Scope:  
source  
Type:  
VirtualMTA name  
Attributes: optional  
Default:  
none  
Specifies the default VirtualMTA (or VirtualMTA pool) to select for all messages  
received from the source. If process-x-virtual-mta is also enabled for the  
source, the default VirtualMTA can be overridden by means of a x-virtual-mta  
header.  
“by-smtp-source-ip“ can be used in place of a VirtualMTA name. When  
configured in this way, on an inbound SMTP connection PowerMTA will use as  
the default VirtualMTA whose "smtp-source-host" setting equals the destination  
IP address on the inbound connection.  
Example:  
<virtual-mta mta1>  
smtp-source-host 1.2.3.4 vmta1.port25.com  
</virtual-mta>  
<source 0/0>  
default-virtual-mta by-smtp-source-ip  
</source>  
In the above example, connecting to IP address 1.2.3.4 would automatically route  
the message through VirtualMTA “mta1”. Also, during the connection from the  
external mailer to PowerMTA, PowerMTA would respond with the host name  
configured in the VirtualMTA.  
45  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
disconnect-on-transient-error  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Specifies that PowerMTA should close connections instead of sending transient  
SMTP errors. This is useful in situations where the feeding software cannot  
process 4xx errors.  
hide-message-source  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies that PowerMTA should attempt to hide the source of the message while  
delivering e-mail from this source. Currently, this just means that the name and IP  
address of the MTA from which PowerMTA received this message will not be  
included in the Received: header added. Hiding the message's source may be  
desirable, for example, for security purposes, to avoid revealing details from the  
internal network from which the message was submitted.  
log-resolution  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies that PowerMTA should log information on DNS (name and routing)  
lookups performed for the domain. This information is generally useful when  
debugging DNS-based connectivity problems (such as misconfigured DNS  
entries).  
Example:  
<domain hotmail.com>  
log-resolution true  
</domain>  
46  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
log-transfer-failures  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should write a warning to the logging file when  
connections fail while transferring message's contents (headers and body). Setting  
this directive to true may help when diagnosing delivery problems, especially  
duplicate or partial deliveries.  
max-message-size  
Scope:  
Type:  
source  
number  
Attributes: optional  
Default:  
unlimited  
Specifies the maximum size allowed in messages received through SMTP. If set  
to unlimited, no explicit limit is enforced.  
max-message-hops  
Scope:  
Type:  
source  
number  
Attributes: optional  
Default:  
100  
Specifies the maximum number of "Received" headers to accept in a message.  
max-rcpt-per-message  
Scope:  
source  
Type:  
number  
Attributes: optional  
Default:  
0
Specifies the maximum number of recipients accepted in each message. If set to  
zero, no explicit limit is enforced.  
47  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
too-many-rcpts-fails-message  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Specifies how PowerMTA should enforce the max-rcpt-per-message limit. If  
enabled and too many recipients are passed for a message, rather than reject the  
extraneous recipient(s) (RCPT SMTP command), PowerMTA rejects the entire  
message (DATAcommand).  
pattern-list  
Scope:  
Type:  
source  
pattern list name  
Attributes: optional  
Default:  
none  
Specifies that messages received from the source are to be matched against the  
given pattern list. The pattern list referenced must precede the source definition in  
the configuration file. Section 3.2.16 describes pattern lists in greater detail.  
process-x-envid  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should process x-envidheaders. If set to trueand  
one such header is included, PowerMTA will set the message's (DSN) envelope  
ID to the header's body, as well as remove the header from the message. If set to  
false, PowerMTA will ignore this header, leaving it in the message if present.  
While the envelope ID can be set by using the ENVID parameter in the SMTP  
MAIL command, this directive is useful when the software you use to submit the  
messages does not allow you to control it.  
48  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
process-x-dkim-options  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should process x-dkim headers. If set to trueand  
one such header is included, PowerMTA will use any values in the header for  
signing messages with DKIM if DKIM signing is configured. If set to false,  
PowerMTA will ignore this header, leaving it in the message if present.  
process-x-job  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should process x-job headers. If set to true and  
one such header is included, PowerMTA will set the job ID for the message to the  
job ID given in the x-jobheader. The job ID must not include any non-printable  
or white space characters. A message is supposed to include at most one x-job  
header. If using Mailmerge, you must use the *jobid variable, and not the x-job  
header.  
x-job: abc123  
jobid-header  
Scope:  
Type:  
source  
string  
Attributes: optional  
Default:  
Allows setting an alternate header for which the message's jobId is set in place of  
using x-job. If other ways to set a jobId (such as x-job processing, if enabled, or  
*jobId mail merge variable) apply, they take precedence.  
49  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
retain-x-job  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should retain a processed x-job header in the  
message. If set to true, PowerMTA will keep the x-job header in the message  
when sending it on, otherwise that header will be removed. This option is only  
used if process-x-jobis set to trueand the message contains an x-jobheader.  
process-x-virtual-mta  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should process x-virtual-mta headers. If set to  
true and one such header is included, PowerMTA will select the VirtualMTA  
specified in the header's body for the message, as well as remove the header from  
the message. If set to false, PowerMTA will ignore this header, leaving it in the  
message if present.  
You should enable this directive for the source IP addresses from which you feed  
messages if you would like to use the x-virtual-mta header to select which  
VirtualMTA to use. You should probably not enable this globally (e.g., in the 0/0  
entry) since this way any messages coming into PowerMTA would be scanned for  
that header. That would apply, for example, even for remote bounces being  
received through PowerMTA.  
retain-x-virtual-mta  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should retain a processed x-virtual-mta header  
in the message. If set to true, PowerMTA will keep the x-virtual-mta header  
in the message when sending it on, otherwise that header will be removed. This  
option is only used if process-x- virtual-mta is set to true and the message  
contains an x-virtual-mta header.  
50  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
smtp-await-slot  
Scope:  
global  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should wait for a new connection slot when a new  
(incoming) SMTP connection request is received but no more slots are available.  
If set to false, PowerMTA responds with a 421 greeting, indicating that the  
service is not available, and closes the connection.  
source-group  
Scope:  
Type:  
source  
string  
Attributes: optional  
Default:  
Specifies the name of a source group to associate the given source to, allowing  
linking sources to groups (and thus grouping sources). The directive affects  
incoming SMTP connections from the given group of <source> tags. The  
directive allows for specifying certain source configuration items whose  
functionality require them to be grouped by name. The shared resources will be  
defined in the <source-group> tag. To add a <source> to the shared resource,  
specify the name of the <source-group> in the <source> tag. An example  
would look similar to the following:  
<source-group localSources>  
max-smtp-in 10  
reserved-smtp-in 5  
</source-group>  
<source 192.168.0.30>  
smtp-service yes  
always-allow-relaying yes  
source-group localSources  
</source>  
<source 192.168.0.40>  
smtp-service yes  
always-allow-relaying yes  
source-group localSources  
</source>  
Each <source> that defines the source-group directive of the same name will be  
controlled by the settings in the named <source-group>tag.  
51  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-smtp-in  
Scope:  
source-group  
number  
Type:  
Attributes: optional  
Default:  
unlimited  
Specifies a limit for the number of incoming connections from that source group.  
reserved-smtp-in  
Scope:  
Type:  
source-group  
number  
Attributes: optional  
Default:  
unlimited  
Specifies that a certain number of inbound connections are to be reserved to  
connections from the given source group.  
smtp-ip  
Scope:  
Type:  
global  
IP address  
Attributes: optional  
Default:  
all local IP addresses  
On a multi-homed host, this directive specifies the IP address on which  
PowerMTA is to listen for incoming connections. Doing so frees up the SMTP  
port for other uses on all other IP addresses — as long as the other SMTP  
software can be instructed to bind itself to specific IP addresses. In a different  
scenario, for security reasons you may also want to have PowerMTA listen for  
connections on an internal, non-routable IP address only.  
See also smtp-listenerbelow.  
Example:  
# listen on internal IP address only  
smtp-ip 10.0.0.1  
52  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
smtp-port  
Scope:  
Type:  
global  
number  
Attributes: optional  
Default:  
25 (standard SMTP port)  
Specifies the TCP port number to use for listening for incoming SMTP  
connections, allowing you to "run PowerMTA on a non-standard port". This can  
be useful if a second mailer handles all incoming traffic while PowerMTA is fed  
through another TCP port. If smtp-portis set to 0, PowerMTA does not listen for  
incoming connections (and feeding is only possible through the submission APIs).  
See also smtp-listenerbelow.  
Example:  
# use port 2525 since port 25 is used by mailer X  
smtp-port 2525  
53  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
smtp-listener  
Scope:  
global  
Type:  
IP address:port  
Attributes: optional  
Default:  
none  
Specifies an IP address and port to listen for incoming SMTP connections. Multiple smtp-  
listener entries can be specified in a configuration file, each of which specifying a  
different IP address and/or port. 0.0.0.0 may be used more than once to set multiple ports  
for all IP addresses on the system. A CIDR IP address range can also be specified,  
however if this is used, the address 0.0.0.0 cannot be used. If any smtp-listener  
directives are specified, PowerMTA ignores the smtp-ip and smtp-port directives.  
However, if no smtp-listener directives are specified, one listener is implicity started  
with the address given by smtp-ipand smtp-port.  
smtp-listeneraccepts an optional source=... parameter which allows you to specify a  
<source> entry with settings to override those obtained from the normal matching by  
source IP address.  
It also takes tls=… parameter, defaulted to 'no', to enable SMTPS  
(SMTP over TLS from the beginning of the connection, with the need for STARTTLS)  
Example:  
smtp-listener 1.2.3.4:25 source=mta1 tls=yes  
smtp-listener 0.0.0.0:26  
<source mta1>  
default-virtual-mta mta1  
</source>  
<source 10.0.0.0/8>  
allow-mailmerge yes  
always-allow-relaying yes  
</source>  
<source 0/0>  
allow-mailmerge no  
always-allow-relaying no  
</source>  
In the example above, VirtualMTA mta1 is selected by default for any messages received  
through 1.2.3.4. Permission for relaying and for using the mailmerge extensions are  
granted to connections coming from 10.*, whether they connect to 1.2.3.4 or not.  
Warning If you specify always-allow-relaying on a source selected from a smtp-  
listener directive, anybody who can connect to the given IP address will be allowed to  
relay. In doing so, you might be creating an "open SMTP relay".  
54  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
smtp-service  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether to allow access to the SMTP service to connections from the  
given source. If set to false, PowerMTA issues a 5XX SMTP greeting like  
521 hostname does not accept mail from you  
instead of the regular one:  
220 hostname (PowerMTA version) ESMTP service ready  
Note that since the default is to grant SMTP service, if you only wish to restrict  
service to specific sources you must specify that in the 0/0 entry, as in the  
example below.  
Example:  
<source 10.0.0.1>  
smtp-service yes  
# we feed from 10.0.0.1  
always-allow-relaying yes  
</source>  
<source 0/0>  
smtp-service no  
</source>  
# normally desirable for feeder sources  
55  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3.2.24 Web-Based Monitor Directives  
http-mgmt-port  
Scope:  
Type:  
global  
number  
Attributes: optional  
Default:  
8080  
Specifies the TCP port number for the web-based monitor. Since there is no  
standard port for this application, other software running on the same host may  
already be using that port. In this case, change the port to some free port number.  
If http-mgmt-portis set to 0, no web-based monitor is started.  
Example:  
# use port 8888 since our proxy uses 8080  
http-mgmt-port 8888  
Changing this directive requires a restart of the pmtahttp service.  
http-access  
Scope:  
Type:  
global  
IP value  
Attributes: Required  
Default:  
127.0.0.1 monitor  
The new directive has the format "http-access CIDR {none|monitor|admin}",  
where CIDR is an IP address or CIDR mask specification. The keyword after the  
CIDR gives the level of access: none, monitor (read-only) or admin (read-write).  
Admin access is intended for things that actually modify PowerMTA's state  
(configuration, LAK, queues, etc.). The directive can be specified several times,  
and builds an access list in which IP addresses are matched from top to bottom.  
Example:  
# allow internal hosts access to the web-based monitor  
http-access 10.0.0.0/8 monitor  
Use of this directive requires a restart of the pmtahttp service.  
56  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
http-mgmt-source & no-http-mgmt-source  
Scope:  
Type:  
global  
boolean  
Attributes: Required  
Default:  
These functions have been deprecated. Please use http-access.  
Example:  
# allow internal hosts access to the web-based  
monitor  
http-access 10.0.0.0/8 monitor  
3.2.25 Logging Directives  
http-log-data  
Scope:  
Type:  
global  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether web monitor data exchanges are logged or not. More verbose  
than http-log-requests.  
http-log-requests  
Scope:  
global  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether web monitor data exchanges are logged or not.  
log-auto-rotation  
Scope:  
global  
Type:  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether the logging files are to be rotated automatically at midnight.  
See the log-rotatedirective for more information on file rotation.  
57  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
log-file  
Scope:  
Type:  
global  
file name  
Attributes: required  
Default:  
Specifies the name of PowerMTA's logging file. On Windows NT/2000, it can be  
either specified with a path name relative to the installation directory or with an  
absolute path. On Unix it must always be specified as an absolute path.  
Example:  
#windows  
log-file log\pmta.log  
#linux  
log-file /var/log/pmta/pmta.log  
log-rotate  
Scope:  
Type:  
global  
number  
Attributes: optional  
Default:  
see text  
Specifies the number of files to keep when rotating the logging files. File rotation  
is a practical way of preventing files from growing too large and, at the same  
time, ensure that the most recent data is available in case it is needed.  
When the log files are rotated, PowerMTA renames the existing logging files,  
attaching a number to them, starting with 1 for the most recent file. On Unix,  
assuming a file named log, that's log.N -> log.N+1, log -> log.1 and on  
Windows NT/2000 (assuming log.txt), log-N.txt -> log-N+1.txt, log.txt  
-> log-1.txt. It then creates a new file (either log or log.txt) to which it  
continues writing logging information.  
The number passed includes the file currently being written to, so a value of 1  
means only the current file is kept (but no older files), 2 means the current file  
plus one old file, and so on. A value of 0 disables rotation entirely. That is the  
default on Linux, since rotation is normally done with the logrotate script (a  
default configuration is placed in /etc/logrotate.d/pmta when PowerMTA is  
installed). On Windows NT/2000 and Solaris, the default is 8, i.e., seven older  
files are retained.  
58  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
log-resolution  
Scope:  
domain  
boolean  
Type:  
Attributes: optional  
Default:  
false  
Specifies that PowerMTA should log information on DNS (name and routing)  
lookups performed for the domain. This information is generally useful when  
debugging DNS-based connectivity problems (such as misconfigured DNS  
entries).  
Example:  
<domain hotmail.com>  
log-resolution true  
</domain>  
log-connections  
Scope:  
Type:  
domain, source  
boolean  
Attributes: optional  
Default:  
false  
Instructs PowerMTA to write an entry in the log at the beginning and end of each  
connection.  
Examples:  
<domain hotmail.com>  
log-connections yes  
</domain>  
# log *all* incoming connections  
<source 0/0>  
log-connections yes  
</source>  
59  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
log-commands  
Scope:  
domain, source  
boolean  
Type:  
Attributes: optional  
Default:  
false  
Instructs PowerMTA to log the full SMTP protocol exchanges between itself and  
the receiving or sending mailer. Since it displays at which point of the delivery  
process an error occurs, enabling this directive is generally the first and most  
useful step in debugging connectivity problems.  
Example:  
<domain aol.com>  
log-commands yes  
</domain>  
Log output:  
2003-06-29 15:32:00 ( 20)starting aol.com  
2003-06-29 15:32:00 ( 20)connecting to yh.mx.aol.com (205.188.157.1)  
2003-06-29 15:32:00 ( 20)>>> 220-rly-yh01.mx.aol.com ESMTP relay_in.5; Thu, 29 Jun 2003  
09:27:58 -0400  
2003-06-29 15:32:00 ( 20)>>> 220-America Online (AOL) and its affiliated companies do  
not  
2003-06-29 15:32:00 ( 20)>>> 220-  
computer  
2003-06-29 15:32:00 ( 20)>>> 220-  
unsolicited bulk  
authorize the use of its proprietary computers and  
networks to accept, transmit, or distribute  
e-mail sent from the internet.  
2003-06-29 15:32:00 ( 20)>>> 220  
2003-06-29 15:32:00 ( 20)<<< EHLO hazmat.port25.com  
2003-06-29 15:32:00 ( 20)>>> 250-rly-yh01.mx.aol.com hazmat.port25.com  
2003-06-29 15:32:00 ( 20)>>> 250 HELP  
...  
60  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
log-data  
Scope:  
Type:  
domain, source  
boolean  
Attributes: optional  
Default:  
false  
This directive is useful for debugging protocol or interoperability problems  
between the mailers, for it logs every byte sent, both in ASCII and hexadecimal.  
This would help show things like whether your messages may be finishing its  
lines with just LF (line feeds) instead of the CRLF (carriage return, line feed) pair  
as prescribed by the standards, and the hex data allows you to identify non-  
printable characters (such as CR and LF) based on their hex codes.  
Example:  
<domain yahoo.com>  
log-data yes  
</domain>  
Log output:  
2003-06-29 09:53:59 ( 19)starting yahoo.com  
2003-06-29 09:53:59 ( 19)connecting to mx1.mail.yahoo.com (128.11.68.155)  
2003-06-29 09:54:04 ( 19)>>> rd 53  
2003-06-29 09:54:04 ( 19)3232302059536D7470206D7461313334 220 YSmtp mta134  
2003-06-29 09:54:04 ( 19)2E6D61696C2E7961686F6F2E636F6D20 .mail.yahoo.com  
2003-06-29 09:54:04 ( 19)45534D54502073657276696365207265 ESMTP service re  
2003-06-29 09:54:04 ( 19)6164790D0A  
2003-06-29 09:54:04 ( 19)<<< wr 24  
ady..  
2003-06-29 09:54:04 ( 19)45484C4F2068617A6D61742E706F7274 EHLO hazmat.port  
2003-06-29 09:54:04 ( 19)32352E636F6D0D0A  
2003-06-29 09:54:04 ( 19)>>> rd 75  
25.com..  
2003-06-29 09:54:04 ( 19)3235302D6D74613133342E6D61696C2E 250-mta134.mail.  
2003-06-29 09:54:04 ( 19)7961686F6F2E636F6D0D0A3235302D38 yahoo.com..250-8  
2003-06-29 09:54:04 ( 19)4249544D494D450D0A3235302D53495A BITMIME..250-SIZ  
2003-06-29 09:54:04 ( 19)4520333134353732380D0A3235302050 E 3145728..250 P  
2003-06-29 09:54:04 ( 19)4950454C494E494E470D0A  
2003-06-29 09:54:04 ( 19)<<< wr 43  
IPELINING..  
2003-06-29 09:54:04 ( 19)4D41494C2046524F4D3A3C696E666F40 MAIL FROM:<info@  
2003-06-29 09:54:04 ( 19)706F727432352E636F6D3E20424F4459 port25.com> BODY  
2003-06-29 09:54:04 ( 19)3D384249544D494D450D0A  
2003-06-29 09:54:04 ( 19)>>> rd 33  
=8BITMIME..  
2003-06-29 09:54:04 ( 19)3235302073656E646572203C696E666F 250 sender <info  
2003-06-29 09:54:04 ( 19)40706F727432352E636F6D3E206F6B0D @port25.com> ok.  
2003-06-29 09:54:04 ( 19)0A  
2003-06-29 09:54:04 ( 19)<<< wr 29  
...  
.
61  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
log-transfer-failures  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should write a warning to the logging file when  
connections fail while transferring message's contents (headers and body). Setting  
this directive to true may help when diagnosing delivery problems, especially  
duplicate or partial deliveries.  
log-file-world-readable  
Scope:  
global  
Type:  
boolean  
Attributes: optional  
Default:  
true  
Grants the web monitor access to read and display the log files that have been  
rotated.  
62  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-events-recorded  
Scope:  
Type:  
domain  
number  
Attributes: optional  
Default:  
10  
Specifies the number of events PowerMTA is to record about the given domain.  
These events are not written to the logging file, but just recorded in memory.  
They can be viewed using the pmta show domains and the pmta show  
topdomains commands, or via the web interface. While recording such events  
can be very useful when investigating delivery problems, may have have an  
impact on memory consumption. Currently only error events are recorded.  
Example:  
Configuration file:  
<domain port25.com>  
max-events-recorded 3  
</domain>  
At the command prompt:  
$ pmta show dom port25.com --errors  
-----------------------------domain --#rcpt ---kbytes conn last error----------  
port25.com  
4
0.5  
0 ETIMEDOUT connect...  
2003-06-19 16:40:10 ETIMEDOUT connecting to mail.port25.com (193.96.192.241)  
2003-06-19 16:40:10 ETIMEDOUT connecting to mail.port25.com (193.96.192.241)  
2003-06-19 16:40:10 ETIMEDOUT connecting to mail.port25.com (193.96.192.241)  
1 of 10 domains shown.  
63  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3.2.26 Accounting Directives  
The accounting File can be written to CSV, pipe, or the older binary style. Directives  
with scope acctfile apply to the CSV, and directives starting with acct- apply to the binary  
file. For more information on the accounting file, see Section 11.  
delete-after  
Scope:  
Type:  
acct-file  
{#d|never}  
Attributes: optional  
Default:  
8d (8 days)  
This directive tells PowerMTA how long to keep the accounting file before  
deleting it from the server. "delete-after" only applies if "move-to" isn't active"  
(and move-to must point to a different location than the directory where the file  
was originally created).  
move-to  
Scope:  
Type:  
acct-file  
directory  
Attributes: optional  
Default:  
files not moved  
This directive tells PowerMTA where to move the accounting file when using  
move-interval or max-size. If move-to isn't set, no moving is done (move-  
interval is silently ignored). Directory must be on the same volume as the  
accounting files. Moving across a network is not supported.  
move-interval  
Scope:  
Type:  
acct-file  
time interval  
Attributes: optional  
Default:  
5m  
This directive tells PowerMTA at what time interval to move the accounting file  
and start a new one.  
64  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
max-size  
Scope:  
Type:  
acct-file  
{n{B|K|M|G|T}|unlimited}  
Attributes: optional  
Default:  
50M  
The max size of the accounting file in Bytes, Kilobytes, Megabytes, Gigabytes, or  
Terabytes before PowerMTA moves the accounting file and starts a new one.  
Minimum size is 1M (1000000B & 1000K) & Maximum size is 1T. This  
directive applies both with and without "move-to". If "move-to" is not specified,  
a new file is started in place (with a higher –NNNN in the file name).  
retry-interval  
Scope:  
Type:  
acct-file  
time interval  
Attributes: optional  
Default:  
5m  
Retries the pipe program in a regular interval in case of a failure. This should  
only be used when using pipe to write an accounting file.  
iso-times  
Scope:  
Type:  
acct-file  
boolean  
Attributes: optional  
Default:  
yes  
Allows requesting that PowerMTA formats time stamps in the accounting file (or  
pipe) in ISO format.  
user-string  
Scope:  
Type:  
acct-file  
string  
Attributes: optional  
Default:  
Specifies a custom string to be stored along with other MTA information in  
theaccounting file.  
65  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
write-timeout  
Scope:  
acct-file  
Type:  
time interval  
Attributes: optional  
Default:  
1m  
Allows for setting write timeouts in accounting pipes, so that an unresponsive  
accounting application doesn't hold up PowerMTA indefinitely. Only used when  
pipeing accounting data to another file.  
map-header-to-field  
Scope:  
acct-file  
Type:  
string  
Attributes: optional  
Default:  
Allows for mapping a header to a specific field in the accounting file. This is  
useful if for example the from header needs to be mapped to the SMTP MAIL  
FROM address (“orig” field in the accounting file). An example would be like  
the following:  
map-header-to-field b header_x-foo rcpt  
map-header-to-field d header_x-bar rcpt  
map-header-to-field d header_x-baz rcpt  
map-header-to-field d header_x-foo orig  
In the above example header_x-foo gets mapped to the rcpt field in bounced  
records, and header_x-bar gets mapped to the rcpt field for delivered records.  
Multiple entries may be specified to map multiple headers to the same field.  
The tq record type cannot be used.  
The order of the directives is significant when using multiple ones for the same  
record type and field. In the above example the rcpt field will contain the content  
of the x-foo header if x-foo exists, if not it will contain the content of the x-bar  
header if that one exists. Otherwise the content of the x-baz header. If that one  
also doesn't exist it will contain the original value of the orig field (i.e. the rcpt  
field will not be overwritten).  
The same header can be mapped to multiple fields (e.g. header_x-foo above) and  
will be written to all fields mapped.  
66  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
records  
Scope:  
Type:  
acct-file  
one or more comma-separated record types  
Attributes: optional  
Default:  
d,b  
This directive tells PowerMTA which record types to include in the accounting  
file. There are 8 record types: d, b, t, tq, r, f, rb, & rs.  
“d” is for delivered records and will include all messages that were  
successfully delivered. “delivery” can be used in place of “d”.  
“b” is for bounced records and will include all locally generated bounces  
(synchronous bounces). Note that bounces generated by remote mail servers  
(asynchronous bounces) will not be included. “bounce” can be used in place  
of “b”.  
“t” is for transient recipient level errors only (such as mailbox full).  
“transient” can be used in place of “t”.  
“tq” is for queue wide transient errors and will include information about  
delivery attempts for a given domain/vmta. “transient-queue” can be used  
in place of “t”.  
“r” is for inbound records and will include information about messages  
submitted to PowerMTA for delivery. “receipt” can be used in place of “r”.  
“f” is for feedback loop emails if PowerMTA is configured to look for  
feedback loop emails with the <feedback-loop-processor>. “feedback-loop”  
may be used in place of “f”. See Section 12.7 for more information.  
“rb” is for remote bounce emails if PowerMTA is configured to look for  
remote bounce emails with the <bounce-processor>. “remote-bounce” may  
be used in place of “rb”. See Section 12.6 for more information.  
“rs” is for remote status emails if PowerMTA is configured to look for remote  
status emails with the <bounce-processor>. “remote-status” may be used in  
place of “rs”. See Section 12.6 for more information.  
Due to the fact that there can be many delivery attempts for one message, it is  
suggested that type “t” and/or “tq” should only be used when needed (debugging,  
troubleshooting, etc.) as it may cause large file sizes. It is also recommended  
when using this setting to have the “t” or “tq” type records written to their own  
file, as so not to cause unwanted data in the primary accounting file.  
67  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
record-fields  
Scope:  
acct-file  
Type:  
record type followed by a comma-separated list of field names  
Attributes: optional  
Default:  
*
This directive specifies the fields to be included in the records defined via the  
"record" directive, in the accounting file. By default all per record type are  
included. To include only a subset of all the fields, simply add the desired fields  
in a comma separated list. To include a custom header, add the record field  
header_XXX, where XXX is the name of the custom field you wish to log. For  
example, to log all fields and a custom header, the directive would look like this:  
record-fields delivery *,header_Message-Id  
To include only a subset of the fields, list the required fields similar to the  
following:  
record-fields bounce timeLogged,orig,rcpt,dlvSourceIp,vmta  
To exclude fields from the default, you can use an “!” to exclude the unwanted  
fields. For example, to include all fields except orcpt you would use:  
record-fields d *,!orcpt  
record-fields b *,!orcpt  
world-readable  
Scope:  
Type:  
acct-file  
boolean  
Attributes: optional  
Default:  
no  
This directive tells PowerMTA what read permissions to set on the accounting  
file.  
68  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
count-moved-records  
Scope:  
Type:  
acct-file  
boolean  
Attributes: optional  
Default:  
false  
This directive tells PowerMTA whether or not to count the records in CSV files  
moved. The record counts are written to the logging file along with the message  
that indicates that the file was moved.  
sync  
Scope:  
Type:  
acct-file  
boolean  
Attributes: optional  
Default:  
no  
Determines whether the OS' buffers for the accounting file are flushed regularly.  
This helps ensure that the accounting data isn't corrupted in case of a system  
crash.  
acct-auto-rotation  
Scope:  
Type:  
global  
boolean  
Attributes: optional  
Default:  
true  
Deprecated, please use <acct-file> tag and directives.  
Specifies whether the accounting files are to be rotated automatically at midnight.  
See the log-rotate directive in Section 3.2.6 for more information on file  
rotation.  
69  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
acct-file  
Scope:  
Type:  
global  
file name  
Attributes: optional  
Default:  
accounting disabled  
Deprecated, please use <acct-file> tag and directives.  
Specifies the name of PowerMTA's accounting file. On Windows NT/2000, it can  
be either specified with a path name relative to the installation directory or with  
an absolute path. On Unix it must always be specified as an absolute path. See  
Section 11 for more information on the accounting file.  
acct-log-header  
Scope:  
Type:  
global  
header name  
Attributes: required  
Default:  
none  
Deprecated, please use <acct-file> tag and directives.  
Specifies which headers PowerMTA includes in the accounting file. PowerMTA  
writes header and content of the specified header to the accounting record for the  
email the header is found in. This directive may be used more than once. You  
cannot specify x-envid, x-job, or x-virtual-mta, since these are written to the  
accounting file anyway. The header name is case-insensitive. It may not contain  
whitespace.  
Example: Specifying acct-log-header x-myid and sending a message that  
contains an x-myid: foo header will have PowerMTA write x-myid and foo to  
the accounting record for that message.  
acct-rotate  
Scope:  
Type:  
global  
number  
Attributes: optional  
Default:  
see text  
Deprecated, please use <acct-file> tag and directives.  
Specifies the number of accounting files for the automatic file rotation. See the  
log-rotatedirective in Section 3.2.6 for more information.  
70  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
acct-move-to  
Scope:  
global  
Type:  
directory name  
Attributes: optional  
Default:  
Deprecated, please use <acct-file> tag and “move-to”.  
Specifies the directory to which the accounting files are moved, and must specify  
the absolute path to a directory in the same file system (or "volume" in Windows  
terms) as the accounting file. For example, if the original accounting file is on  
C:\pmta\log\, the file cannot be moved to D:\acct. It can only be moved to  
another place on the C:\ drive. If "acct-move-to" is specified, no accounting  
rotation must be active. "acct-rotate" must not be in the configuration, or it must  
be set to 0.  
acct-move-interval  
Scope:  
global  
Type:  
number  
Attributes: optional  
Default:  
5m  
Deprecated, please use <acct-file> tag and directives.  
Specifies in the same format as "bounce-after", how frequently the accounting file  
should be moved. The default is 5 minutes.  
On Unix systems, logrotate's  
configuration should be modified to prevent rotation of accounting files. When  
the files are moved to the target directory, they are renamed with a time stamp  
indicating when they were moved, such as "acct-20070501120000.dat" on  
Windows and "acct-20070501120000" on Unix. If a file with that name already  
exists, an additional "-N" suffix is added to the name, where N is a number to  
make it unique. Applications reading from that destination directory can start  
processing the file as soon as it is moved there, but should ignore all files whose  
names begin with "." or end in ".tmp".  
71  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
acct-move-max-size  
Scope:  
Type:  
global  
number  
Attributes: optional  
Default:  
50  
Deprecated, please use <acct-file> tag and directives.  
Specifies that PowerMTA should move the accounting file (provided that 'acct-  
move-to' is defined) once it's reached the given size. The size is specified in  
megabytes, and defaults to 50 MB.  
Like acct-move-interval, this directive  
specifies an approximate number; the size of the moved accounting file will  
almost always be a little larger than specified.  
acct-user-string  
Scope:  
Type:  
global  
string  
Attributes: optional  
Default:  
none  
Deprecated, use “user-string”.  
user-string  
Scope:  
Type:  
global  
string  
Attributes: optional  
Default:  
none  
Specifies a custom string to be stored along with other MTA information in the  
accounting file.  
72  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
acct-write-msgDlv  
Scope:  
Type:  
global  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether or not PowerMTA writes information about successful  
deliveries in the accounting file.  
This directive is relevant for sites who only want to see DSN/bounce reports in  
the accounting file. Please note that if the setting is false (meaning successful  
deliveries are not written to the accounting file), once a message is delivered, its  
accountability within PowerMTA is gone and PowerMTA will have no record of  
this message.  
73  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
deliver-local-dsn  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
true  
This directive instructs PowerMTA whether or not to generate and deliver a  
Delivery Status Notification (DSN) for a message. DSNs are more widely  
referred to or known as bounce reports, however non-bounce DSNs exist as well.  
Regardless if set to true or false, PowerMTA will write the final bounce detail in  
the PowerMTA accounting file when PowerMTA receives a permanent/5xx error  
from the remote host during the connection, or when the error is generated by  
PowerMTA. The default setting is true, which instructs PowerMTA to generate  
and attempt to deliver the DSN report, as well as write the bounce detail in the  
accounting file.  
If set to false, PowerMTA does not even create the DSN report, it just efficiently  
writes the bounce detail in the accounting file for processing. A setting of false is  
the correct setting for sites that parse only the accounting file data for the locally  
generated bounce reports (also referred to "sychronous" or "inline" bounces), and  
do not want to have any bounce reports generated/sent to the SMTP MAIL  
FROM address.  
For consistency with previous versions of PowerMTA, these records are still  
labeled as <repDlv> records in the accounting file. Since the bounce detail is now  
logged when the error is received and not when the bounce report is actually  
delivered, <repDlv> records will not contain certain fields that existed previously,  
that related to the actual delivery of the bounce report. The fields that will not be  
included are:  
<dlvFrom>, <dlvThrough>, and <size>, since these were all  
determined at the time the bounce report was to be delivered.  
The deliver-local-dsn directive is as per domain directive, and which should be  
defined for the SMTP MAIL FROM domain, since this is the address that DSN  
reports are sent. To have it apply to all local bounce reports regardless of the  
SMTP MAIL FROM domain (e.g. if your messages have a different SMTP MAIL  
FROM domain depending on the customer/client or campaign) simply define this  
directive within the global <domain *> definition. For example, the following  
setting would apply to messages whose SMTP MAIL FROM domain was  
bounce.port25.com, regardless of the original recipient address:  
<domain bounce.port25.com>  
deliver-local-dsn no  
</domain>  
74  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3.2.27 General Queueing and Delivery Directives  
bounce-after  
Scope:  
Type:  
domain  
time interval  
Attributes: optional  
Default:  
4 days, 12 hours  
Determines the maximum amount of time PowerMTA will continue to try to  
deliver messages to the specified destination domain. Messages older than this  
time interval are bounced, i.e., a (non-)delivery report in DSN format will be sent  
back to the originator.  
allow-priority-interruption  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
yes  
When set to "no", this directive prevents interruptions by higher priority queues.  
allow-priority-interruption-during-transfer  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
no  
When set to 'no', the interruption is delayed until a connection is available. When  
set to 'yes', the interruption to an existing connection happens immediately. This  
directive applies to SMTP queues only.  
queue-priority  
Scope:  
Type:  
domain  
number  
Attributes: optional  
Default:  
50  
When PowerMTA needs to deliver email for a queue but no connection slots are  
available, it looks for a queue with lower priority currently connected and  
interrupts as many connections as needed, starting with the lowest priority  
connections and working its way up. A queue's priority is set with a number  
between 0 (lowest) and 100 (highest); 50 by default.  
75  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
delivery-priority  
Scope:  
Type:  
domain  
number  
Attributes: optional  
Default:  
50  
Deprecated, use queue-priority.  
dk-sign  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether or not PowerMTA should perform Domain Keys signing on  
messages destined for this domain. Domain keys must be configured for this  
directive to take effect.  
Please see the domain-keydirective below for more information.  
NOTE: In previous versions, the default for this directive was true, and as such,  
you may need to change this in your configuration file at the time of an upgrade.  
dkim-sign  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether or not PowerMTA should perform DKIM signing on messages  
destined for this domain. Domain keys must be configured for this directive to  
take effect.  
Please see the domain-keydirective below for more information.  
NOTE: In previous versions, the default for this directive was true, and as such,  
you may need to change this in your configuration file at the time of an upgrade.  
76  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
dkim-identity  
Scope:  
domain  
string  
Type:  
Attributes: optional  
Default:  
sender-or-from  
Specifies the domain or email address of the signing identity to be used when  
signing messages with DKIM. (Supported in the DKIM specification only). If  
defined, and the domain matches, or is a subdomain of the domain defined in the  
"domain-key" directive, the domain will be used in place of the Sender or From:  
header domain for signing and for subsequent key verification by the receiving  
gateways. This may be useful for those who are sending on behalf of another  
party, and do not have control of the other party's DNS record. A service  
provider for example, can sign mail using their own private key, use their own  
email address/domain as the signing identity, and have their own public key in  
their own DNS record for validation, all while having the From: header domain  
in the messages sent being the domain of their customer. The "dkim-identity"  
address will be seen in the i= parameter in the signature, while the d= parameter  
is set via the domain used in the "domain-key" directive and which has to match  
or be the parent domain in the dkim-identity directive.  
Note that receiving gateways will normally judge a message based on the  
reputation of the domain of the signing identity.  
Example:  
domain-key key1,esp123.com,c:\pmta\m.pem  
<domain yahoo.com>  
dkim-sign yes  
dkim-identity @esp123.com  
#
#
dkim-identity sender-or-from  
dkim-identity email@esp123.com  
</domain>  
In the above example, the "From:" or "Sender:" headers can be a different  
domain then "esp123.com", but it will be the domain "esp123.com" that will be  
used for the signing, and, the public key in the TXT record in DNS for the  
domain "key1._domainkey.esp123.com" will be the one checked for verification.  
77  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
dkim-identity-fallback  
Scope:  
Type:  
domain  
string  
Attributes: optional  
Default:  
“”  
Specifies an alternative DKIM identity to use if the primary identity isn't usable  
(usually because no keys are matched). This allows PowerMTA to use the dkim  
key for the From or Sender header if available ( eg. domain-key directive), but if  
the key is not available, PowerMTA switches to using the dkim-identity-fallback  
for signing (i= specified email address in the signature).  
dkim-identity.  
Requires the use of  
Example:  
domain-key key1,esp456.com,c:\pmta\m.pem  
<domain yahoo.com>  
dkim-sign yes  
dkim-identity sender-or-from  
dkim-identity-fallback @esp456.com  
</domain>  
78  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
domain-key  
Scope:  
Type:  
global, virtual mta  
see text  
Attributes: optional  
Default:  
none  
Specifies a domain key to use for messages delivered through the given  
VirtualMTA or for any messages if configured at the global level. You can  
specify multiple domain-key entries. PowerMTA determines the key to use by  
going through the keys sequentially and picking the first key whose domain either  
equals or is a parent of the message's sending domain. If there are matching  
domain keys at both the global level and the VirtualMTA level, the VirtualMTA's  
domain keys take precedence. The sending domain is that of the Sender header,  
or, if Sender is not present, of the From header. If no keys match the sending  
domain, the message is not signed.  
The wildcard “*” may be used in place of a domain. This will cause all messages  
to be signed using the sending domain (extracted from the headers).  
For more information on how to set up DomainKeys, please see Section 10.4.2.  
Example:  
<virtual-mta mta1>  
...  
domain-key m,mail.port25.com,c:\pmta\m.pem  
domain-key base,*,c:\pmta\base.pem  
</virtual-mta>  
or  
domain-key m,mail.port25.com,c:\pmta\m.pem  
domain-key base,*,c:\pmta\base.pem  
79  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
invalid-virtual-mta-fallback  
Scope:  
Type:  
global  
VirtualMTA name  
Attributes: optional  
Default:  
none  
Specifies a fallback VirtualMTA to select for messages for which an invalid (non-  
existant) VirtualMTA was selected. By using this directive, you prevent  
PowerMTA from bouncing messages for which an invalid VirtualMTA was  
selected. Instead, the messages are delivered from the fallback VirtualMTA.  
This directive only works when feeding PowerMTA. It does not work with  
reroute-to-virtual-mta or backoff-reroute-to-virtual-mta.  
queue-to  
Scope:  
Type:  
domain  
string  
Attributes: optional  
Default:  
none  
Allows for grouping domains with the same MX record together. See section  
10.7 for more informaiton.  
log-tls  
Scope:  
Type:  
domain, source  
boolean  
Attributes: optional  
Default:  
Yes  
Enables TLS-specific logging.  
80  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
log-connections  
Scope:  
domain, source  
boolean  
Type:  
Attributes: optional  
Default:  
false  
Instructs PowerMTA to write an entry in the log at the beginning and end of each  
connection.  
Examples:  
<domain hotmail.com>  
log-connections yes  
</domain>  
# log *all* incoming connections  
<source 0/0>  
log-connections yes  
</domain>  
81  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
log-commands  
Scope:  
domain, source  
boolean  
Type:  
Attributes: optional  
Default:  
false  
Instructs PowerMTA to log the full SMTP protocol exchanges between itself and  
the receiving or sending mailer. Since it displays at which point of the delivery  
process an error occurs, enabling this directive is generally the first and most  
useful step in debugging connectivity problems.  
Example:  
<domain aol.com>  
log-commands yes  
</domain>  
Log output:  
2003-06-29 15:32:00 ( 20)starting aol.com  
2003-06-29 15:32:00 ( 20)connecting to yh.mx.aol.com (205.188.157.1)  
2003-06-29 15:32:00 ( 20)>>> 220-rly-yh01.mx.aol.com ESMTP relay_in.5; Thu, 29 Jun 2003  
09:27:58 -0400  
2003-06-29 15:32:00 ( 20)>>> 220-America Online (AOL) and its affiliated companies do  
not  
2003-06-29 15:32:00 ( 20)>>> 220-  
computer  
2003-06-29 15:32:00 ( 20)>>> 220-  
unsolicited bulk  
authorize the use of its proprietary computers and  
networks to accept, transmit, or distribute  
e-mail sent from the internet.  
2003-06-29 15:32:00 ( 20)>>> 220  
2003-06-29 15:32:00 ( 20)<<< EHLO hazmat.port25.com  
2003-06-29 15:32:00 ( 20)>>> 250-rly-yh01.mx.aol.com hazmat.port25.com  
2003-06-29 15:32:00 ( 20)>>> 250 HELP  
...  
82  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
log-data  
Scope:  
Type:  
domain, source  
boolean  
Attributes: optional  
Default:  
false  
This directive is useful for debugging protocol or interoperability problems  
between the mailers, for it logs every byte sent, both in ASCII and hexadecimal.  
This would help show things like whether your messages may be finishing its  
lines with just LF (line feeds) instead of the CRLF (carriage return, line feed) pair  
as prescribed by the standards, and the hex data allows you to identify non-  
printable characters (such as CR and LF) based on their hex codes.  
Example:  
<domain yahoo.com>  
log-data yes  
</domain>  
Log output:  
2003-06-29 09:53:59 ( 19)starting yahoo.com  
2003-06-29 09:53:59 ( 19)connecting to mx1.mail.yahoo.com (128.11.68.155)  
2003-06-29 09:54:04 ( 19)>>> rd 53  
2003-06-29 09:54:04 ( 19)3232302059536D7470206D7461313334 220 YSmtp mta134  
2003-06-29 09:54:04 ( 19)2E6D61696C2E7961686F6F2E636F6D20 .mail.yahoo.com  
2003-06-29 09:54:04 ( 19)45534D54502073657276696365207265 ESMTP service re  
2003-06-29 09:54:04 ( 19)6164790D0A  
2003-06-29 09:54:04 ( 19)<<< wr 24  
ady..  
2003-06-29 09:54:04 ( 19)45484C4F2068617A6D61742E706F7274 EHLO hazmat.port  
2003-06-29 09:54:04 ( 19)32352E636F6D0D0A  
2003-06-29 09:54:04 ( 19)>>> rd 75  
25.com..  
2003-06-29 09:54:04 ( 19)3235302D6D74613133342E6D61696C2E 250-mta134.mail.  
2003-06-29 09:54:04 ( 19)7961686F6F2E636F6D0D0A3235302D38 yahoo.com..250-8  
2003-06-29 09:54:04 ( 19)4249544D494D450D0A3235302D53495A BITMIME..250-SIZ  
2003-06-29 09:54:04 ( 19)4520333134353732380D0A3235302050 E 3145728..250 P  
2003-06-29 09:54:04 ( 19)4950454C494E494E470D0A  
2003-06-29 09:54:04 ( 19)<<< wr 43  
IPELINING..  
2003-06-29 09:54:04 ( 19)4D41494C2046524F4D3A3C696E666F40 MAIL FROM:<info@  
2003-06-29 09:54:04 ( 19)706F727432352E636F6D3E20424F4459 port25.com> BODY  
2003-06-29 09:54:04 ( 19)3D384249544D494D450D0A  
2003-06-29 09:54:04 ( 19)>>> rd 33  
=8BITMIME..  
2003-06-29 09:54:04 ( 19)3235302073656E646572203C696E666F 250 sender <info  
2003-06-29 09:54:04 ( 19)40706F727432352E636F6D3E206F6B0D @port25.com> ok.  
2003-06-29 09:54:04 ( 19)0A  
2003-06-29 09:54:04 ( 19)<<< wr 29  
...  
.
83  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-events-recorded  
Scope:  
Type:  
domain  
number  
Attributes: optional  
Default:  
10  
Specifies the number of events PowerMTA is to record about the given domain.  
These events are not written to the logging file, but just recorded in memory.  
They can be viewed using the pmta show domains and the pmta show  
topdomains commands, or via the web interface. While recording such events  
can be very useful when investigating delivery problems, may have have an  
impact on memory consumption. Currently only error events are recorded.  
Example:  
Configuration file:  
<domain port25.com>  
max-events-recorded 3  
</domain>  
At the command prompt:  
$ pmta show dom port25.com --errors  
-----------------------------domain --#rcpt ---kbytes conn last error----------  
port25.com  
4
0.5  
0 ETIMEDOUT connect...  
2003-06-19 16:40:10 ETIMEDOUT connecting to mail.port25.com (193.96.192.241)  
2003-06-19 16:40:10 ETIMEDOUT connecting to mail.port25.com (193.96.192.241)  
2003-06-19 16:40:10 ETIMEDOUT connecting to mail.port25.com (193.96.192.241)  
1 of 10 domains shown.  
84  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-smtp-msg-rate  
Scope:  
Type:  
virtual-mta  
{unlimited|0|N/{h|hr|m|min|s|sec}  
Attributes: optional  
Default:  
unlimited  
Allows for entering per-minute and per-second transfer rates directly. It accepts  
the following values: "unlimited", "N/h" or “N/hr” (for per-hour), "N/m" or  
“N/min” (for per-minute) and "N/s" or “N/sec” (for per-second). "max-msg-rate"  
and "max-msg-per-hour" modify the same internal setting and thus override each  
other when set.  
<virtual-mta customer1>  
max-smtp-msg-rate 6/sec  
</virtual-mta>  
Both deliveries and attempted deliveries are counted towards the limit. The  
following error will be displayed in the web monitor when the rate limit is  
reached:  
“message rate limit reached (based on max-smtp-msg-rate in configuration)”  
When using rate limiting, it is best to establish a baseline without rate limiting to  
ensure that the limits set are having a positive impact on deliverability.  
85  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-msg-rate  
Scope:  
domain  
Type:  
{unlimited|0|N/{h|hr|m|min|s|sec}  
Attributes: optional  
Default:  
unlimited  
Allows for entering per-minute and per-second transfer rates directly. It accepts  
the following values: "unlimited", "N/h" or “N/hr” (for per-hour), "N/m" or  
“N/min” (for per-minute) and "N/s" or “N/sec” (for per-second). "max-msg-rate"  
and "max-msg-per-hour" modify the same internal setting and thus override each  
other when set.  
<domain comcast.net>  
max-msg-rate 6/sec  
</domain>  
Both deliveries and attempted deliveries are counted towards the limit. The  
following error will be displayed in the web monitor when the rate limit is  
reached:  
“message rate limit reached (based on max-msg-rate in configuration)”  
When using rate limiting, it is best to establish a baseline without rate limiting to  
ensure that the limits set are having a positive impact on deliverability.  
backoff-max-msg-rate  
Scope:  
domain  
Type:  
number  
Attributes: optional  
Default:  
unlimited  
This directive has the same function as max-msg-rate, and applies instead of max-  
msg-rate while a queue is in backoff mode.  
Both deliveries and attempted deliveries are counted towards the limit. The  
following error will be displayed in the web monitor when the rate limit is  
reached:  
“message rate limit reached (based on backoff-max-msg-rate in configuration)”  
When using rate limiting, it is best to establish a baseline without rate limiting to  
ensure that the limits set are having a positive impact on deliverability.  
86  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-msg-per-hour  
Scope:  
domain  
number  
Type:  
Attributes: optional  
Default:  
unlimited  
Deprecated, use max-msg-rate.  
backoff-max-msg-per-hour  
Scope:  
domain  
Type:  
number  
Attributes: optional  
Default:  
unlimited  
Deprecated, use backoff-max-msg-rate  
retry-after  
Scope:  
Type:  
domain  
time interval  
Attributes: optional  
Default:  
10 minutes  
Determines the delivery retry interval for messages that were not delivered on the  
initial attempt.  
backoff-retry-after  
Scope:  
domain  
Type:  
time interval  
Attributes: optional  
Default:  
one hour  
This directive has the same function as retry-after, and applies instead of  
retry-afterwhile a queue is in backoff mode.  
87  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
backoff-notify  
Scope:  
domain  
Type:  
e-mail address  
Attributes: Optional  
Default: ""(no notification sent)  
Specifies e-mail addresses to notify when any of the queues for the given domain  
enters or leaves backoff mode. Multiple addresses may be specified in a comma  
separated list.  
Example:  
<domain *>  
backoff-notify two@host.domain,one@host.domain  
</domain>  
backoff-to-normal-after  
Scope:  
domain  
Type:  
time {Nd|h|m|s|}  
Attributes: optional  
Default:  
never  
Specifies a time interval after which a queue automatically goes back to normal  
mode. Example:  
<domain *>  
backoff-to-normal-after 6h  
</domain>  
backoff-to-normal-after-delivery  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
If enabled, this puts a queue back into normal mode after a successful delivery.  
88  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
backoff-upon-all-sources-disabled  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
If enabled, switches a queue into backoff mode upon all sources being disabled  
when using the <smtp-pattern-list> function disable-source-ip.  
reenable-source-ip-after  
Scope:  
domain  
Type:  
boolean  
Attributes: optional  
Default:  
never  
Sets the interval of time before an IP disabled with the <smtp-pattern-list>  
function disable-source-ip is re-enabled.  
89  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
auto-cold-virtual-mta  
Scope:  
Type:  
virtual-mta  
IP host-name  
Attributes: optional  
Default:  
When starting to send email from a new IP address, it is sometimes important to  
control the amount of traffic sent from that IP, so that reputation can be built  
properly.  
To facilitate this task, PowerMTA supports for automatically  
configuring separate queues and diverting part of the traffic to those queues.  
The per-vmta directive "auto-cold-virtual-mta IP hostname" enables the re-  
selection and internally configures a "...-cold" VirtualMTA. If used more than  
once in a VirtualMTA, the additional auto defined VirtualMTAs will use the  
naming format of “...-cold-1”, “…-cold-2”, etc. The auto defined VirtualMTA  
will use globally inherited <domain> settings. Defining the cold VirtualMTA  
explicitly when using auto-cold-virtual-mta is not supported. Please use the  
directive “cold-virtual-mta” to define and config the cold VirtualMTA explicitly.  
As a side effect of these changes, when selecting a VirtualMTA pool, the specific  
vmta assigned is persisted on disk (doesn't change upon a restart).  
Cold vmta re-selection takes place during feeding, so you'll need to feed in more  
messages daily if you want to ensure the limit gets used up. The counters are  
reset at midnight.  
Re-selection can be used with pools, too. In that case the next vmta in the pool is  
first selected and, if below the limit, the re-selection takes place.  
Both the limits and the selection are persisted on disk, so that you can safely re-  
start PowerMTA. The current limit state is also saved every 10 minutes.  
The directive can be repeated to configure multiple cold VirtualMTAs, in which  
case these are used in round-robin fashion and the per-domain limit applies  
individually for each cold VirtualMTA.  
Example:  
<virtual-mta warm>  
auto-cold-virtual-mta 1.2.3.4 cold1.yourdomain.com  
auto-cold-virtual-mta 5.6.7.8 cold2.yourdomain.com  
</virtual-mta>  
90  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
cold-virtual-mta  
Scope:  
virtual-mta  
Type:  
VirtualMTA-name  
Attributes: optional  
Default:  
Original use of the directive is now deprecated (e.g. cold-virtual-mta IP/CIDR  
hostname). For original usage see auto-cold-virtual-mta.  
This directive now takes the name of a manually configured VirtualMTA. The  
VirtualMTA does not need to maintain the format of “…–cold”, and instead may  
be named any valid VirtualMTA name.  
The directive can be repeated to configure multiple cold VirtualMTAs, in which  
case these are used in round-robin fashion and the per-domain limit applies  
individually for each cold VirtualMTA.  
Example:  
<virtual-mta coldvmta1>  
smtp-source-host 1.2.3.4 cold1.yourdomain.com  
</virtual-mta>  
<virtual-mta coldvmta2>  
smtp-source-host 5.6.7.8 cold2.yourdomain.com  
</virtual-mta>  
<virtual-mta warmvmta1>  
cold-virtual-mta coldvmta1  
cold-virtual-mta coldvmta2  
<domain *>  
max-cold-virtual-mta-msg 1000/d  
</domain>  
</virtual-mta>  
91  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-cold-virtual-mta-msg  
Scope:  
Type:  
domain  
N/d  
Attributes: optional  
Default:  
0/d  
A per-domain "max-cold-virtual-mta-msg N/day", default of 0, specifies how  
many messages go to the "foo-cold" vmta when VirtualMTA "foo" is selected.  
Re-selection occurs at message reception and over SMTP only. The valued  
specified is the first X amount of messages for that domain. The defined amount  
is set for delivery upon injection.  
<virtual-mta vmat1>  
smtp-source-host 192.168.0.9 mail.yourdomain.com  
cold-virtual-mta 192.168.0.10 mail1.yourdomain.com  
<domain *>  
max-cold-virtual-mta-msg 1000/d  
</domain>  
</virtual-mta>  
Please note that this setting is per domain, so 1000 emails will go to yahoo, 1000  
will go to hotmail, etc.  
92  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
backoff-reroute-to-virtual-mta  
Scope:  
Type:  
domain  
VirtualMTA name  
Attributes: optional  
Default:  
none  
Specifies that PowerMTA should reroute messages to the given VirtualMTA in  
case the queue enters backoff mode. For example, if messages are queued for  
example.port25.corm/vmta1 and that queue enters backoff mode while  
backoff-reroute-to-virtual-mtais set to vmta2, all of its messages would be  
rerouted to the queue example.port25.com/vmta2. New messages entering the  
queue are also rerouted, as long as the queue remains in backoff mode.  
Example:  
<virtual-mta vmta1>  
...  
</virtual-mta>  
<virtual-mta vmta2>  
...  
</virtual-mta>  
<domain *>  
backoff-reroute-to-virtual-mta vmta2  
</domain>  
It may also make sense to use this directive on a per VirtualMTA basis:  
<virtual-mta vmta1>  
...  
<domain *>  
backoff-reroute-to-virtual-mta vmta2  
</domain>  
</virtual-mta>  
<virtual-mta vmta2>  
...  
</virtual-mta>  
WARNING: PowerMTA performs full loop detection on this directive. If a loop  
is detected, messages are left in the last queue in the loop, and an error is written  
to the log file.  
A reroute from one VirtualMTA to itself is silently ignored, and a reroute to a  
VirtualMTA pool is not supported.  
93  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
type  
Scope:  
Type:  
domain  
smtp, pipe, file, or discard  
Attributes: optional  
Default:  
see text  
Determines whether e-mail for this domain is to be delivered over SMTP, through  
the pipe delivery API, to a file, or discarded.  
The default for the * domain is smtp, which unless overriden is inherited by all  
other domains.  
File delivery writes messages to files, just like the Pipe API sample programs  
appendtofile and newfile (see Section 7.5.2). The difference is that while the  
built-in file delivery is faster, pipe delivery is more flexible (since it allows you  
roll your own delivery programs). See Section 3.2.11 for file delivery-specific  
directives.  
Discard delivery discards the e-mail, after writing the corresponding accounting  
record and including the e-mail in the traffic counters. Discard delivery is useful if  
you are only interested in the accounting records.  
include-headers-from  
Scope:  
Type:  
virtual mta  
file name  
Attributes: optional  
Default:  
none  
Specifies the name of a file containing RFC2822-formatted headers to insert in all  
messages delivered from a VirtualMTA. The headers are inserted immediately  
after the Receivedheader added by PowerMTA. This directive requires a restart  
of PowerMTA.  
domain-macro  
Scope:  
Type:  
global  
list  
Attributes: optional  
Default:  
none  
Specifies the variable and bindings for domain macro expansion. Only letters &  
numbers are supported when naming a domain-macro. See the domain scope in  
Section 3.2 for more information on usage.  
94  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
accept-invalid-recipients  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
no  
Allows feeding invalid recipients into PowerMTA (which are then immediately  
bounced). Invalid in this sense means syntactically illegal email addresses (i.e.,  
me@there or you@yahoo..com), but not e.g., bad mailboxes (syntactically correct  
but non-existent email addresses). Pickup directory supported only when used  
with “XACK off”.  
virtual-mta  
Scope:  
Type:  
virtual mta pool  
VirtualMTA name  
Attributes: optional  
Default:  
none  
Specifies the name of a VirtualMTA to include in the pool. To specify multiple  
VirtualMTAs, repeat this directive with the name of each VirtualMTA to add.  
Example:  
<virtual-mta mta1>  
...  
</virtual-mta>  
<virtual-mta mta2>  
...  
</virtual-mta>  
<virtual-mta-pool pool>  
virtual-mta mta1  
virtual-mta mta2  
</virtual-mta-pool>  
3.2.28 SMTP Delivery Directives  
The directives in this Section are ignored if specified in non-SMTP domains.  
95  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
allow-cancel-during-transfer  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether PowerMTA should allow connections to this domain to be  
cancelled (e.g., in order to shut down PowerMTA) while a message's contents  
(headers and body) are being transferred. Some mailers have been known to still  
deliver messages if the connection breaks before they are fully received, lastly  
causing partial and duplicate messages to be delivered as PowerMTA retries  
delivering. Setting this directive to false prevents PowerMTA from cancelling  
connections while messages are being transferred on it, but also possibly causes  
PowerMTA to take longer to shut down.  
auth-username  
Scope:  
Type:  
domain  
string  
Attributes: optional  
Default:  
none  
Specifies the user name to use when authenticating to the remote mailer.  
Authentication is attempted if the AUTH extension as well as a SASL  
authentication mechanism supported by PowerMTA are available at the remote  
mailer, and either auth-usernameor auth-passwordhave non-empty values.  
PowerMTA currently only supports the CRAM-MD5, LOGIN, & PLAIN  
authentication mechanisms.  
smtp-data-termination-timeout  
Scope:  
Type:  
domain  
time  
Attributes: optional  
Default:  
10m  
Allows for setting the amount of time that PowerMTA will wait for the final "250  
ok" response after sending the message body. Setting this value too low is likely  
to cause duplicates.  
96  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
assume-delivery-upon-data-termination-timeout  
Scope:  
Type:  
domain  
Boolean  
Attributes: optional  
Default:  
no  
If enabled and the connection times out while waiting for the reply to the "." after  
a DATA or for the reply to the last BDAT segment, PowerMTA assumes that the  
delivery was successful.  
auth-password  
Scope:  
Type:  
domain  
string  
Attributes: optional  
Default:  
none  
Specifies the password to use when authenticating to the remote mailer. Please  
see the auth-usernamedirective above for more information.  
use-unencrypted-plain-auth  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should use PLAIN and/or LOGIN for  
authentication in case the connection is not encrypted (i.e., if STARTTLS is not  
being used).  
smtp-553-means-invalid-mailbox  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
yes  
Instructs PowerMTA whether to default to a 5.1.1 upon a 553 reply to a RCPT  
command and no enhanced status code is provided in the reply.  
97  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
smtp-421-means-mx-unavailable  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
no  
If set to “yes”, PowerMTA will immediately break the connection upon receiving  
a 421 error and subsequently attempt a new connection to the next MX record  
listed in DNS. The default setting of “no” will cause PowerMTA to reset the  
connection and then reuse the same connection for additional recipients.  
bounce-upon-no-mx  
Scope:  
domain  
Type:  
boolean  
Attributes: optional  
Default:  
false  
If set to "true" and no MX records are found for the domain, all emails in the  
queue bounce immediately. Note that this applies only to cases where a MX  
lookup is performed, which does not include cases where a host list is specified in  
the "route" directive (unless it contains only domain name, in which case a MX  
lookup is performed).  
bounce-upon-5xx-greeting  
Scope:  
domain  
Type:  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether PowerMTA should immediately bounce all messages for the  
domain when receiving a 5xx SMTP greeting. E-mail protocols mandate this  
default behavior, however there exist many misconfigured mailers on the  
network, causing e-mail to be lost unnecessarily. If this directive is set to false,  
PowerMTA will regard 5xx greetings as a temporary error and try delivering the  
messages to any secondary MX mailers, as well continue retrying delivery until  
the bounce-afterinterval expires.  
98  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
bounce-upon-pix-transfer-failure  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
This directive is identical to the bounce-upon-transfer-failure directive  
below, except that the message is only bounced if a Cisco PIX Firewall is  
detected at the receiving site. Detection is performed based on the SMTP greeting  
line: if it contains at least ten asterisks, a PIX firewall is detected.  
bounce-upon-transfer-failure  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should immediately bounce a message whose  
delivery failed while its contents (message headers and body) were being  
transferred. Normally, PowerMTA would not immediately bounce the message,  
but continue trying until it becomes older than the bounce-afterinterval. Due to  
deficiencies in the SMTP protocol (See RFC 1047) and in the receiving mail  
servers, if the TCP connection fails while the contents are being transmitted, there  
is some risk that various copies of the same message will be delivered, some of  
which possibly with only partial contents. By enabling this directive, you instruct  
PowerMTA to bounce the message immediately after the first failed transfer  
attempt. This effectively prevents sending out duplicates, but may also cause the  
recipient to never receive the message, or receive only one (possibly partial) copy  
of it.  
reject-mfrom-check-temperror  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether to reject the MAIL command (with a 4xx error) in the SMTP  
protocol if the "mfrom" check results in a temporary error, such as when unable to  
look up certain DNS records.  
99  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
reject-mfrom-check-permerror  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether to reject the MAIL command (with a 5xx error) in the SMTP  
protocol if the "mfrom" check results in a permanent error, such as when there is a  
syntax error in a SPF record.  
reject-mfrom-check-fail  
Scope:  
source  
Type:  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether to reject the MAIL command (with a 5xx error) in the SMTP  
protocol if the "mfrom" check results in a failure, such as when email is being  
sent from an unauthorized IP address.  
connect-timeout  
Scope:  
Type:  
domain  
time interval  
Attributes: optional  
Default:  
2m (two minutes)  
Specifies the maximum amount of time that PowerMTA waits for an outgoing  
SMTP connection to be established.  
smtp-greeting-timeout  
Scope:  
domain  
Type:  
time interval  
Attributes: optional  
Default:  
5m (five minutes)  
Specifies the amount of time to wait for the initial SMTP 220 greeting message to  
be received after the connection is accepted. Previously PowerMTA waited up to  
10 minutes for the greeting message.  
100  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
data-send-timeout  
Scope:  
Type:  
domain  
time interval  
Attributes: optional  
Default:  
3m (three minutes)  
Specifies the maximum amount of time that PowerMTA waits for a chunk of data  
(message contents and body) to be sent over an outgoing SMTP connection. For  
full compliance with RFC 2821, this timeout needs to be at least three minutes.  
ignore-8bitmime  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should ignore the 8BITMIME extension even when  
supported by the receiving mailer. Setting this directive to true allows you to  
work around the problem of messages bouncing because a site's external MTA  
accepting 8BITMIME messages as such but unable to convert them to 7BIT when  
passing to an internal MTA which does not support 8BITMIME.  
use-starttls  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should use the STARTTLS extension (if supported  
by the receiving mailer). Setting this directive to trueinstructs PowerMTA to use  
that extension to encrypt the connection to the remote mailer, at a cost in  
performance.  
101  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
require-starttls  
Scope:  
domain  
boolean  
Type:  
Attributes: optional  
Default:  
true  
Only relevant if "use-startTls" is enabled. The STARTTLS extension may not be  
available at the remote host, or its use may fail for various reasons. If "require-  
startTls" is set to "true", PowerMTA will abort the connection, thus avoiding to  
send the message through a less secure connection. Otherwise, it will send the  
message anyway.  
ignore-chunking  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should ignore the CHUNKING extension even when  
supported by the receiving mailer. Setting this directive to truemay be useful for  
debugging message transfer problems.  
ignore-pipelining  
Scope:  
domain  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should ignore the PIPELINING extension even  
when supported by the receiving mailer. Setting this directive to true may be  
useful for debugging message transfer problems.  
102  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-msg-per-connection  
Scope:  
Type:  
domain  
number  
Attributes: optional  
Default:  
0
Specifies the maximum number of messages delivered within a single connection.  
Normally it is most efficient to deliver as many messages as possible per  
connection, but in special circumstances it may be desirable to have PowerMTA  
close the connection and reconnect before delivering more messages. A value of  
zero means no limit is imposed.  
max-rcpt-per-message  
Scope:  
domain, source  
Type:  
number  
Attributes: optional  
Default:  
1000  
Alias to max-rcpt-per-transaction.  
max-rcpt-per-transaction  
Scope:  
domain  
Type:  
number  
Attributes: optional  
Default:  
1000  
Specifies the maximum number of recipients passed with each message. For  
example, if a message is submitted including 5,000 recipients for a single domain,  
and max-rcpt-per-message for that domain is set to 3,000, PowerMTA will  
transfer the message twice, once for 3,000 recipients and again for the remaining  
2,000 recipients. Smaller settings increase parallelism by allowing the same  
message to be transferred over several connections to the same domain, but also  
reduce efficiency, since the message contents are transferred several times. max-  
rcpt-per-transactionis an alias to max-rcpt-per-message.  
103  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-smtp-out  
Scope:  
domain, virtual-mta  
number  
Type:  
Attributes: optional  
Default:  
20 for domain, unlimited for virtual-mta  
Specifies the maximum number of simultaneous connections to be opened for  
this domain or VirtualMTA. The actual number of connections opened is  
determined by PowerMTA depending on a variety of parameters and in practice  
rarely exceeds one or two for an individual domain.  
Certain circumstances may warrant increasing this number for specific domains,  
however many sites will have an unpublished maximum number of connections  
allowed at a time, and which can and does change from time to time. So, while  
increasing this number for specific domains could improve throughput  
performance, that is not always the case and ultimately you have to play by the  
rules imposed by the receiving mail servers.  
max-smtp-out-per-source-ip  
Scope:  
Type:  
domain  
number  
Attributes: optional  
Default:  
unlimited  
Specifies the maximum number of simultaneous connections to be opened for this  
domain for a given source IP. The actual number of connections opened is  
determined by PowerMTA depending on a variety of parameters and in practice  
rarely exceeds one or two for an individual domain.  
Certain circumstances may warrant increasing this number for specific domains,  
however many sites will have an unpublished maximum number of connections  
allowed at a time, and which can and does change from time to time. So, while  
increasing this number for specific domains could improve throughput  
performance, that is not always the case and ultimately you have to play by the  
rules imposed by the receiving mail servers.  
104  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-connect-rate  
Scope:  
domain  
Type:  
{unlimited|0|N/{h|hr|m|min|s|sec}  
Attributes: optional  
Default:  
unlimited  
Specifies the maximum number of simultaneous connections to be opened for this  
domain during the specified time period.  
backoff-max-connect-rate  
Scope:  
domain  
Type:  
{unlimited|0|N/{h|hr|m|min|s|sec}  
Attributes: optional  
Default:  
unlimited  
Specifies the maximum number of simultaneous connections to be opened for this  
domain during the specified time period when in backoff mode.  
retry-upon-new-mail  
Scope:  
domain  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies if PowerMTA should immediately schedule delivery of a message when  
it is received if the queue to which it is injected is already in retry mode. If set to  
true and a queue is in retry mode, new mail injected into that queue will cause the  
queue to be scheduled for delivery.  
pix-bug-workaround  
Scope:  
domain  
Type:  
boolean  
Attributes: optional  
Default:  
true  
Some versions of the Cisco PIX firewall have a bug (bug ID CSCds90792) in its  
"fixup smtp" command in that it rejects e-mail (causing duplicates to be  
delivered) if the final .<CR><LF> sequence is split across various TCP frames.  
This directive instructs PowerMTA, in case it detects a PIX firewall, to send the  
final .<CR><LF> in a frame of its own, making it almost certain to arrive at the  
receiving site in a single frame. Detection is performed based on the SMTP  
greeting line: if it contains at least ten asterisks, a PIX firewall is detected.  
105  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
route  
Scope:  
Type:  
domain  
string  
Attributes: optional  
Default:  
none  
Allows you to override the normal DNS-based routing, instructing PowerMTA to  
deliver to the specified host name or IP address. Multiple hosts can be specified in  
a comma and semicolon-separated list. The format of the route string is one of  
the following examples.  
The following specifies a host name, whose IP address will be looked up in the  
DNS.  
<domain SomeDomain.com>  
route OtherDomain.com  
</domain>  
The following specifies an IP address to which PowerMTA is to connect.  
<domain SomeDomain.com>  
route [a.b.c.d]  
</domain>  
The following specifies an IP address and a TCP port number to which  
PowerMTA is to connect.  
<domain SomeDomain.com>  
route [a.b.c.d]:p  
</domain>  
Lastly, the following is an example where commas separate hosts within the same  
priority level, and semicolons separate priority levels. In this example, [a.b.c.d]  
and [e.f.g.h] are the primary, and equal, hosts to contact in round-robin fashion.  
[i.j.k.l] is a backup host for [a.b.c.d] and [e.f.g.h], whereas [m.n.o.p]:p is a backup  
host for [i.j.k.l].  
<domain SomeDomain.com>  
route [a.b.c.d]:25,[e.f.g.h]:25;[i.j.k.l]:2525;[m.n.o.p]:25  
</domain>  
To put the above in a chart format:  
Priority  
Host  
-------------------  
0
0
1
2
[a.b.c.d]  
[e.f.g.h]  
[i.j.k.l]  
[m.n.o.p]  
106  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
mx-connection-limit  
Scope:  
Type:  
global  
string  
Attributes: optional  
Default:  
none  
Per connection limits can be configured with the directive:  
mx-connection-limit mx.domain.com limit  
In the above example, "mx.domain.com" is the MX record that you want to limit  
connections to, and "limit" is either a positive number or the word "unlimited".  
One can define a specific MX record to match on, or use wildcards to define  
multiple MX records, for example, [*.]domain.com, using the same conventions  
available within <domain> tags. The connection limit applies on a per source IP  
address basis (per IP address that PowerMTA will make connections from). If the  
wildcard is used, and multiple records are matched, the connection limit will  
apply per record matched, and not globally across all matches.  
The global directive can be entered several times in the configuration file, once  
per line, forming a list of rules specifying the limits for the various MX records.  
It is important to note that mx.domain.com parameter matches the MX record for  
a domain, and not the recipient domain itself.  
This directive is most useful when an ISP or hosting provider hosts hundreds of  
domains, but has one or few MX records for all of those domains. This directive  
allows you to limit the number of connections per MX, regardless of the number  
of recipient domains you are mailing to. Note again, that the connection limit  
applies on a per source IP address basis and not per virtualMTA.  
mx-connection-limit [*.]secureserver.net 20  
107  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
default-smtp-port  
Scope:  
Type:  
domain  
number  
Attributes: optional  
Default:  
25  
Allows specifying the TCP port to use for delivering over SMTP (unless  
overridden by a "route" directive). This allows people to use the destination port  
to pass on a number (namely, the port number) to their NAT boxes, thus  
simplifying MTA farm setup (because one internal IP address is no longer needed  
per vmta per MTA box).  
smtp-pattern-list  
Scope:  
domain  
Type:  
SMTP pattern list name  
Attributes: optional  
Default:  
none  
Specifies that the given SMTP pattern list is to be used in connections to the given  
domain. The SMTP pattern list referenced must precede the domain definition in  
the configuration file. Section 3.2.17 describes SMTP pattern lists in greater  
detail.  
smtp-source-ip  
Scope:  
Type:  
global, virtual-mta  
IP address or CIDR IP address range  
Attributes: optional  
Default:  
any local IP addresses  
Deprecated, please use smtp-source-host.  
assume-delivery-upon-data-termination-timeout  
Scope:  
Type:  
domain  
boolean  
Attributes: optional  
Default:  
no  
If enabled and the connection times out while waiting for the reply to the "." after  
a DATA or for the reply to the last BDAT segment, PowerMTA assumes that the  
delivery was successful. .May result in duplicate messages if used when not  
needed.  
108  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
smtp-source-host  
Scope:  
global, virtual-mta  
Type:  
IP address or CIDR range and host-name  
Attributes: optional  
Default:  
On a multi-homed host, this directive specifies an IP address (or IP address range)  
and host-name from which PowerMTA is to initiate outgoing SMTP connections.  
This can be useful, for example, to help ensure that PowerMTA complies with  
your firewall policy. Alternatively, you can enter this directive several times  
and/or specify a CIDR IP address range with the host-name, instructing  
PowerMTA to use the various source IP addresses in round-robin fashion. All  
local IP addresses matching the specification are added to the list of source IP  
addresses, except for 127.0.0.1, which is automatically excluded since it can't be  
used to connect to remote hosts.  
When specified within a VirtualMTA, this directive overrides the global source  
IPs for connections established to send messages through the VirtualMTA.  
These IP/host-name pair should match in DNS as the IP/PTR (reverse DNS) pair.  
When multiple pairs are used, any <domain> settings are applied across all pairs,  
and not set individually. For example, in the following:  
<virtual-mta customer1>  
smtp-source-host 192.168.0.10 mail10.yourserver.com  
smtp-source-host 192.168.0.20 mail20.yourserver.com  
smtp-source-host 192.168.0.30 mail30.yourserver.com  
<domain yahoo.com>  
max-smtp-out 12  
</domain>  
</virtual-mta>  
The setting “max-smtp-out 12” will result in no more than 12 connections across  
all three pairs together at one time, not 12 each for a total of 36. Control of  
individual pairs is not currently available, and if needed, separate VirtualMTAs  
can be configured for each pair.  
This may be used in the place of a <virtual-mta-pool> to help with issues around  
backoff mode when using backoff-reroute-to-virtual-mta.  
Using the above  
instead will keep all the messages in the same VirtualMTA (for better control),  
and allow all defined IPs to be used.  
109  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3.2.29 Discard Delivery Directives  
Currently there are no Discard Delivery-specific directives.  
3.2.30 File Delivery Directives  
The directives in this Section are ignored if specified in non-File Delivery domains.  
file-format  
Scope:  
Type:  
domain  
one of: newfile-plain, newfile-pickupor append-mbox  
Attributes: optional  
newfile-plain  
Default:  
Specifies the format of the file(s) to which PowerMTA delivers the messages:  
newfile-plain  
A new file is created for each message, in the directory indicated by  
file-destination. The entire message is written to the file, including  
all headers, but no envelope information.  
newfile-pickup  
A new file is created for each message, in the directory indicated by  
file-destination. In addition to the entire message body and headers,  
the special headers x-sender and x-receiver are included, containing  
the originator and recipient addresses from the message envelope.  
append-mbox  
Messages are appended to the file indicated by file-destination, in  
the unix "mbox" format.  
Like with the sample Pipe Delivery applications, special care must be taken when  
accessing files to which PowerMTA performs file delivery.  
PowerMTA creates new files with the initial "extension" of .tmp and renames  
them to .msg once done. If post-processing these files as they are created, you  
should code to ignore any .tmp files, to avoid processing a file which hasn't yet  
been completely written.  
When appending to a file (for append-mbox), interlocking is performed using  
flock on unix-like platforms and with share options passed to CreateFile on  
Windows. In order to safely access the file while PowerMTA is running, Port25  
recommends using the pmtagetfile application. Please see Section 7.5.3 for  
more information on pmtagetfile.  
110  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
file-destination  
Scope:  
domain  
Type:  
absolute directory or file name  
Attributes: optional  
Default:  
none  
Specifies the directory or file name for file delivery. The directory or file name is  
subjected to the same macro expansion as in the pipe delivery's command line:  
$bodytype  
The message body type (7BIT, 8BITMIMEor BINARYMIME);  
$ctime  
The current date in Unix ctimeformat;  
$envid  
The DSN envelope ID (from MAIL ... ENVID=...);  
$from  
The envelope sender (MAIL FROM) address;  
$isodate  
The current date in the format YYYY-MM-DD;  
$timet  
The current time in numeric (time_t) format;  
$rfctime  
The current date in RFC 822 format;  
$to  
The envelope recipient (RCPT TO) address;  
$user  
The recipient user. That is the local part (mailbox) in the recipient  
address, or, if the local part contains a '+' character, the portion of the  
mailbox to the left of the '+'. For example, in joe+xyzzy@company.com,  
the user would be joe;  
$domain  
The recipient's domain;  
$from, $to, $user and $domain macros always expand in lower case, avoiding  
issues when those are used to create directories and files on case-sensitive file  
systems Examples:  
<domain bounces.xyz.com>  
type file  
file-format newfile-pickup  
file-destination c:/campaigns/bounces  
</domain>  
<domain [*.]bounces.xyzzy.com>  
type file  
file-format append-mbox  
file-destination /my/path/$domain  
</domain>  
111  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
max-rcpt-per-message  
Scope:  
Type:  
source  
number  
Attributes: optional  
Default:  
0
Specifies the maximum number of recipients accepted in each message. If set to  
zero, no explicit limit is enforced.  
112  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3.2.31 Pipe Delivery Directives  
The directives in this Section are ignored if specified in non-pipe domains.  
command  
Scope:  
Type:  
domain  
string  
Attributes: required  
Default:  
none  
Specifies the command to use to start the program which will read from the pipe.  
This directive is required for pipe domains.  
PowerMTA substitutes the following macros in the command line:  
$bodytype  
The message body type (7BIT, 8BITMIMEor BINARYMIME);  
$ctime  
The current date in Unix ctimeformat;  
$envid  
The DSN envelope ID (from MAIL ... ENVID=...);  
$from  
The envelope sender (MAIL FROM) address;  
$timet  
The current time in numeric (time_t) format;  
$rfctime  
The current date in RFC 822 format;  
$to  
The envelope recipient (RCPT TO) address;  
$user  
The recipient user. That is the local part (mailbox) in the recipient  
address, or, if the local part contains a '+' character, the portion of the  
mailbox to the left of the '+'. For example, in joe+xyzzy@company.com,  
the user would be joe;  
$domain  
The recipient's domain;  
To prevent any one of these macros from being interpreted as multiple arguments  
if they contain spaces, it is a good idea to enclose them in double quotes (like in  
the example below).  
Example:  
<domain bounces.xyz.com>  
type pipe  
command "/my/bounce/processor --envid \"$envid\" \"$user\""  
</domain>  
113  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
3.2.32 Submission API Directives  
always-allow-api-submission  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
no  
This directive allows easily enabling all SMTP permissions and features required  
by our submission APIs. If set to "yes", this is currently equivalent to setting  
"allow-mailmerge yes". If set to "no", the other settings determine whether  
submission is allowed.  
pickup  
Scope:  
Type:  
global  
see text  
Attributes: optional  
Default:  
none  
This directive specifies the path to a "pickup directory" from which PowerMTA  
processes e-mail submissions, as well as the path to a corresponding "bad mail"  
directory to which improperly formatted messages are moved. See Section 7.4 for  
more information on the pickup directory.  
Only one pickup directory is  
supported. A restart of the service is required when adding or changing the  
directive.  
See Section 3.2.13.1 for directives that apply to only the messages in the pickup  
directory.  
Example:  
Pickup c:\Inetpub\Mailroot\Pickup c:\Inetpub\Mailroot\BadMail  
pickup-retry-interval  
Scope:  
Type:  
global  
time interval  
Attributes: optional  
Default:  
5 minutes  
This directive specifies the amount of time to wait before retrying any messages  
whose pickup failed with a temporary error.  
114  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
3.2.33 Source {Pickup}  
For directives that apply only to messages in the pickup directory, use <source {pickup}>  
with the following directives. PowerMTA will still accept <source pickup>, but a  
warning saying it's deprecated will be returned. Use <source {pickup}> instead.  
dsn-return-default  
Scope:  
Type:  
source {pickup}  
full, headersor system  
Attributes: optional  
system  
Default:  
Specifies the default for the DSN RET parameter, i.e., whether the full message  
body or only its headers should be returned in a DSN delivery report. system  
specifies that the system default should be used. This directive is overridden by  
the use of "dsn-format plain-text".  
default-virtual-mta  
Scope:  
source {pickup}  
Type:  
VirtualMTA name  
Attributes: optional  
Default:  
none  
Specifies the default VirtualMTA to select for all messages received from the  
source. If process-x-virtual-mta is also enabled for the source, the default  
VirtualMTA can be overriden by means of a x-virtual-mtaheader.  
process-x-virtual-mta  
Scope:  
source {pickup}  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should process x-virtual-mta headers. If set to  
true and one such header is included, PowerMTA will select the VirtualMTA  
specified in the header's body for the message, as well as remove the header from  
the message. If set to false, PowerMTA will ignore this header, leaving it in the  
message if present.  
115  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
process-x-envid  
Scope:  
source {pickup}  
boolean  
Type:  
Attributes: optional  
Default:  
true  
Specifies whether PowerMTA should process x-envidheaders. If set to trueand  
one such header is included, PowerMTA will set the message's (DSN) envelope  
ID to the header's body, as well as remove the header from the message. If set to  
false, PowerMTA will ignore this header, leaving it in the message if present.  
process-x-job  
Scope:  
Type:  
source {pickup}  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether PowerMTA should process x-job headers. If set to true and  
one such header is included, PowerMTA will set the job ID for the message to the  
job ID given in the x-jobheader. The job ID must not include any non-printable  
or white space characters. A message is supposed to include at most one x-job  
header. If using Mailmerge, you must use the *jobid variable, and not the x-job  
header.  
add-message-id-header  
Scope:  
source {pickup}  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether PowerMTA should add a Message-Id header if missing. If a  
Message-Idheader is present, it is not overridden.  
116  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
add-received-header  
Scope:  
Type:  
source {pickup}  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether PowerMTA should add a Received header upon reception of  
an email.  
pattern-list  
Scope:  
Type:  
source {pickup}  
pattern list name  
Attributes: optional  
Default:  
none  
Specifies that messages received from the source are to be matched against the  
given pattern list. The pattern list referenced must precede the source definition in  
the configuration file. Section 3.2.16 describes pattern lists in greater detail.  
hide-message-source  
Scope:  
source {pickup}  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies that PowerMTA should attempt to hide the source of the message while  
delivering e-mail from this source. Currently, this just means that the name and IP  
address of the MTA from which PowerMTA received this message will not be  
included in the Received: header added. Hiding the message's source may be  
desirable, for example, for security purposes, to avoid revealing details from the  
internal network from which the message was submitted.  
117  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
3.2.34 Dummy SMTP ("blackholing") Directives  
dummy-smtp-ip  
Scope:  
Type:  
global  
IP address  
Attributes: optional  
Default:  
all local IP addresses  
Specifies the IP address on which PowerMTA is to listen for incoming  
connections that are to be handled as "dummy" SMTP connections.  
dummy-smtp-port  
Scope:  
Type:  
global  
number  
Attributes: optional  
Default:  
0 (disabled)  
Specifies the TCP port on which PowerMTA is to listen for incoming connections  
that are to be handled as "dummy" SMTP connections.  
dummy-smtp-await-slot  
Scope:  
global  
Type:  
boolean  
Attributes: optiona  
Default:  
false  
Specifies whether PowerMTA should wait for a new connection slot when a new  
dummy SMTP connection request is received but no more slots are available. If  
set to false, PowerMTA responds with a 421 greeting, indicating that the service  
is not available, and closes the connection.  
dummy-smtp-has-chunking  
Scope:  
global  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether dummy SMTP connections are to support the CHUNKING  
SMTP extension.  
118  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
dummy-smtp-has-pipelining  
Scope:  
Type:  
global  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether dummy SMTP connections are to support the PIPELINING  
SMTP extension.  
dummy-smtp-has-verp  
Scope:  
global  
Type:  
boolean  
Attributes: optional  
Default:  
false  
Specifies whether dummy SMTP connections are to support the VERP SMTP  
extension.  
dummy-smtp-latency  
Scope:  
global  
Type:  
number  
Attributes: optional  
Default:  
0
Specifies the network latency, in milliseconds, to be simulated in dummy SMTP  
connections.  
dummy-smtp-update-stats  
Scope:  
global  
Type:  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether dummy SMTP connections should update the traffic statistics  
displayed by e.g. the web-based Status Monitor.  
3.2.35 Pattern List Directives  
Pattern lists allow you to select a VirtualMTA based on the message's originator, the  
message's recipient, a message header, or a combination of the three.  
119  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
The directives described in this section define a list of regular expression patterns. Each  
entry in a pattern list has the following form:  
directive parameters /pattern/ virtual-mta=name,recipient-priority=n  
where:  
directive is one of the directives below, specifying what is matched.  
parameters additional information depending on the chosen directive; currently  
only the header directive supports a parameter, which is the message header you  
want to match.  
pattern is a perl-compatible regular expression.  
name is the VirtualMTA selected.  
n is the priority of the recipient using a scale of 0-100 with 0 being the lowest  
priority and 100 being the highest with a default of 50 when not specified. This  
may be used without selecting a VirtualMTA.  
If multiple entries match, the first match is used.  
An x-virtual-mtaheader may be used in conjunction with a <pattern-list> to set a  
recipient-priority.  
For more information on perl-compatible regular expressions, please refer to the Perl  
documentation or the PCRE library package.  
120  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
header  
Scope:  
Type:  
pattern list  
see text  
Attributes: optional  
Default:  
none  
Adds a pattern match against the specified header. Matching is performed against  
the entire header contents; in particular, any white space characters such as  
blanks, tabs and CR/LFs will still be present. Because of this, when anchoring the  
regular expression with the caret (^) and dollar ($) characters, it is important to  
allow for white space following the caret and preceding the dollar signs,  
respectively. The \s metacharacter is particularly useful for this, since it will  
match all white space characters.  
Example:  
<pattern-list myList>  
header x-eval  
header from  
/^\s*eval/  
/jsmith/  
virtual-mta=evaluation  
virtual-mta=evaluation  
header subject  
</pattern-list>  
/hello world/  
virtual-mta=evaluation  
<source 127.0.0.1>  
...  
pattern-list myList  
</source>  
# this selects the pattern list for messages  
# from 127.0.0.1  
mail-from  
Scope:  
Type:  
pattern list  
see text  
Attributes: optional  
Default:  
none  
Adds a pattern match against the message's originator.  
Example:  
<pattern-list myList>  
mail-from /^customerservice/  
</pattern-list>  
virtual-mta=service  
<source 127.0.0.1>  
...  
pattern-list myList  
</source>  
# this selects the pattern list for messages  
# from 127.0.0.1  
121  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
rcpt-to  
Scope:  
Type:  
pattern list  
see text  
Attributes: optional  
Default:  
none  
Adds a pattern match against the message's recipient.  
Example:  
<pattern-list myList>  
rcpt-to /customer/  
</pattern-list>  
virtual-mta=customers  
<source 127.0.0.1>  
...  
pattern-list myList  
</source>  
# this selects the pattern list for messages  
# from 127.0.0.1  
If multiple recipients are specified in a message and more than one match a rcpt-  
to directive, the first match's VirtualMTA will apply to the entire message. This  
behavior may change in the future, so rcpt-to should only be used if you only  
intend to submit single-recipient messages.  
Another example, showing a combination of matching patterns:  
<pattern-list myList>  
header from  
header subject  
header x-eval  
mail-from  
/jsmith/  
/hello world/  
/eval/  
virtual-mta=evaluation  
virtual-mta=evaluation  
virtual-mta=evaluation  
virtual-mta=newsletters  
/newsletter/  
rcpt-to  
/^stud.*@somesite.com$/ virtual-mta=students  
rcpt-to  
rcpt-to  
/password-reset@customer.com/ recipient-priority=90  
/special@customer.com/ virtual-mta=students,recipient-priority=90  
</pattern-list>  
<source 127.0.0.1>  
...  
pattern-list myList  
</source>  
# this selects the pattern list for messages  
# from 127.0.0.1  
Here, each email is first checked for the x-eval header. If it is present and its content  
contains eval, the evaluation VirtualMTA is used. If the x-eval header isn't given or  
does not match the pattern, the mail-from is checked to contain newsletter. If it does,  
the newsletters VirtualMTA is used. Finally, if no VirtualMTA was selected by the  
two matches, the rcpt-tois checked. If it starts with studand ends in @somesite.com,  
the students VirtualMTA is used. If none of the above matched, PowerMTA will use  
the default VirtualMTA.  
122  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
This example shows conditional pattern matching:  
<pattern-list patterns>  
mail-from /newsletter/ <pattern-list>  
rcpt-to /^stud.*@somesite.com$/ virtual-mta=students  
rcpt-to /^staff.*@somesite.com$/ virtual-mta=staff  
* virtual-mta=anything  
</pattern-list>  
rcpt-to /admin/ <pattern-list>  
mail-from /thisdomain.com/ virtual-mta=this  
header x-info /newdata/ virtual-mta=other  
* virtual-mta=anything  
</pattern-list>  
</pattern-list>  
<source 127.0.0.1>  
...  
pattern-list patterns  
</source>  
# this selects the pattern list for messages  
# from 127.0.0.1  
Here, first the MAIL FROM is checked for each email. If the MAIL FROM matches  
“newletter”, a sub-pattern is then used. In this sub-pattern, the RCPT TO is checked, and  
if it matches the pattern, the emails will go to the “students” VirtualMTA, or the “staff”  
VirtualMTA. Anything with “newsletter” in the MAIL FROM that does not match the  
sub-patterns get sent to the wildcard defined “anything” VirtualMTA.  
The second pattern is similar to the above, but first first checks the RCPT TO. If the  
RCPT TO matches, the email is then put through the sub patterns, first checking the  
MAIL FROM, and then for the “x-info” header. Once again, emails with a RCPT  
matching “admin”, but not the sub-patterns will be sent to the VirtualMTA “anything”.  
Emails not matching any patterns will not be sent to a VirtualMTA based on pattern  
matching.  
3.2.36 SMTP Pattern List Directives  
SMTP pattern lists allow you to have PowerMTA change a delivery queue's mode based  
on pattern matching on the SMTP replies received while attempting deliveries.  
SMTP pattern lists currently only accept a single directive (reply). Each entry in a  
pattern list has the following form:  
reply /pattern/ action  
Where:  
pattern is a perl-compatible regular expression.  
action is one or a comma separated list of the following  
o
mode=normal  
123  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
o
o
o
o
o
o
mode=backoff  
skip-mx  
bounce-queue  
bounce-rcpt  
disable-source-ip  
reenable-after  
If multiple conflicting entries match, the first match is used. The following is not  
allowed:  
both mode=backoff and mode=normal  
both skip-mx and bounce-queue  
reenable-after without a preceding disable-source-ip (in the same  
rule)  
more than one reenable-after.  
For more information on perl-compatible regular expressions, please refer to the Perl  
documentation or the PCRE library package.  
skip-mx is intended to help PowerMTA from give up delivering to one or more MXes  
which is just giving a transient recipient-level error. Any patterns matched will result in  
the next MX being used and mail being held in queue, even in the case of a 5xx error.  
bounce-queue will bounce the entire queue immediately if the pattern is matched. The  
original error, as well as the fact that the queue was bounced due to this setting, will be  
recorded in the accounting file.  
bounce-rcpt will bounce the recipient immediately if the pattern is matched. This only  
works for 4xx responses to the RCPT command. The original error, as well as the fact  
that the recipient was bounced due to this setting, will be recorded in the accounting file.  
This will bounce a recipient even if “smtp-421-means-mx-unavailable true” is set.  
disable-source-ip will disable the IP that received the error. The source IP will remain  
disabled until the time period defined by the <domain> directive reenable-source-  
ip-after.  
reenable-after Allows for defining the time after which an IP that has been disabled with  
disable-source-ip will be reenabled. The default is never.  
For example, to put any queues in backoff mode upon reception of certain SMTP replies,  
while bouncing some messages immediately or skipping some MX records:  
124  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
<smtp-pattern-list blockList>  
reply /generating high volumes of.* complaints from AOL/  
mode=backoff  
reply /Excessive unknown recipients - possible Open Relay/ mode=backoff  
reply /^421 .* too many errors/  
reply /permanently deferred/  
reply /too many connections/  
reply /account over quota/  
mode=backoff  
bounce-queue  
skip-mx  
bounce-rcpt  
reply /TS03/  
mode=backoff,disable-source-ip,reenable-after=1h  
</smtp-pattern-list>  
<domain *>  
...  
smtp-pattern-list blockList  
</domain>  
To match on a # (the comment symbol in the configuration file) hexadecimal code may  
be used. For example, to match the pattern “Sender address deferred by rule #CR-IN-  
DEF-2”  
:
<smtp-pattern-list blockList>  
reply /Sender address deferred by rule \x23CR-IN-DEF-2 /  
</smtp-pattern-list>  
mode=backoff  
<domain *>  
...  
smtp-pattern-list blockList  
</domain>  
Backslashes (\) and quotes (“) will need to be escaped with a backslash.  
3.2.37 Other Directives  
auto-qualify-domain  
Scope:  
Type:  
source  
boolean  
Attributes: optional  
Default:  
true  
Specifies whether PowerMTA should automatically qualify the domain name in  
any e-mail addresses received whose domain is not yet fully qualified. For  
example, if MAIL FROM:<user@host> is received and the host running  
PowerMTA is named mail.foo.com, then that address is changed into  
user@host.foo.com. Automatic qualification is done by appending the domain  
suffix, which is also configurable.  
125  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
host-id  
Scope:  
Type:  
global  
number string  
Attributes: optional  
Default:  
When using "add-message-id-header”, host-id specifies a per server unique  
identifier that helps prevent the same message ID from being used on two  
separate instances of PowerMTA (multiple servers). Only takes numbers as a  
value.  
126  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
reroute-to-virtual-mta  
Scope:  
Type:  
domain  
text  
Attributes: optional  
Default:  
Specifies that PowerMTA should reroute messages to the given VirtualMTA.  
This can be set globally like this example:  
<virtual-mta vmta1>  
...  
</virtual-mta>  
<virtual-mta vmta2>  
...  
</virtual-mta>  
<domain aol.com>  
reroute-to-virtual-mta vmta2  
</domain>  
Or, it may also make sense to use this directive on a per VirtualMTA basis:  
<virtual-mta vmta1>  
...  
<domain aol.com>  
reroute-to-virtual-mta vmta2  
</domain>  
</virtual-mta>  
<virtual-mta vmta2>  
...  
</virtual-mta>  
A reroute to a VirtualMTA pool is not supported. “reroute-to-vmta” can be  
used in place of “reroute-to-virtual-mta”.  
domain-suffix  
Scope:  
Type:  
global  
domain  
Attributes: optional  
Default:  
system's domain suffix  
Specifies the domain name to append when an e-mail address is received whose  
domain is not fully qualified.  
127  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
host-name  
Scope:  
Type:  
global, virtual-mta  
domain list  
Attributes: optional  
Default:  
system's host name  
This directive specifies a (fully qualified) host name for the local host. If the  
machine on which PowerMTA is running is known under several names, these  
should all be listed by adding various host-name directives. The first name  
specified is picked as the "main" name and is used for the SMTP greeting  
messages, EHLO/HELOcommands, etc.  
When specified within a VirtualMTA, this directive overrides the global host  
name for messages sent through that VirtualMTA.  
When used, this directives behaves like relay-domain, meaning that it will accept  
all messages for the defined domain.  
include  
Scope:  
Type:  
global, source, domain, virtual-mta, pattern-list,  
file name  
Attributes: optional  
Default:  
none  
This directive specifies an additional configuration file to process. This can be  
used, for example, to facilitate maintenance of the configuration files across  
multiple hosts, by storing those settings which differ from host to host in a  
separate file and including it from the main (common) file. Wildcards may be  
used. An include may be used anywhere including in a <source>, <domain>, or  
<virtual-mta> tag.  
include /etc/pmta/vmtas.txt  
include /etc/pmta/includes/*  
128  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
name-server  
Scope:  
global  
Type:  
IP address  
Attributes: optional  
Default:  
system's name servers  
This directive specifies the IP address of a name server (DNS server) for  
PowerMTA to use. If none is entered, PowerMTA uses the name servers  
configured in the operating system. If more than one name-server is defined,  
PowerMTA will round robin through all defined name servers in a load balancing  
fashion.  
sync-msg-create  
Scope:  
Type:  
global  
boolean  
Attributes: optional  
Default:  
false  
Specifies that PowerMTA should synchronize I/O to disk after receiving a  
message. false yields higher performance, but the message may be lost if the  
system crashes before it can write the data to disk.  
sync-msg-update  
Scope:  
Type:  
global  
boolean  
Attributes: optional  
Default:  
false  
Specifies that PowerMTA should synchronize I/O to disk after updating a  
message (for example, to mark recipients handled). false yields higher  
performance, but if the system crashes before it can write the data to disk, some  
recipients may receive multiple copies of a message.  
129  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
thread-min-priority, thread-max-priority  
Scope:  
Type:  
global  
number  
Attributes: optional, non reloadable  
Default:  
see text  
Unix specific directive. Specifies range of process priorities to use for the various  
threads within PowerMTA. Normally these directives should be left at their  
defaults, however it may be necessary to weight process priorities differently  
when PowerMTA shares a host with other server software. thread-min-  
priorityspecifies the "slower" priority and thread-max-priorityspecifies the  
"faster" priority.  
thread-reuse  
Scope:  
Type:  
global  
boolean  
Attributes: optional, non reloadable  
Default:  
true  
Normally, once a thread is finished with its work (like, for example, handling a  
connection), PowerMTA retains it for later reuse. Setting this directive to false  
causes PowerMTA to discard threads as soon as they are no longer needed,  
avoiding certain external problems such as slowing down the top command on  
Linux. However, this costs some performance and also prevents PowerMTA from  
working around a bug in glibc versions prior to 2.2.2 that severely reduces the  
amount of virtual memory available, possibly causing PowerMTA to crash if the  
queue grows very large.  
130  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
4. PowerMTA Management  
Although PowerMTA has been designed for being as low maintenance as possible, it  
does include various tools for management and troubleshooting. This chapter is intended  
as a guide to daily operations with PowerMTA, for those who wish to actively manage  
and monitor, as well as to troubleshooting the most commonly encountered problems.  
4.1 Management  
4.1.1 Monitoring  
There is a number of ways in which you can monitor PowerMTA. It has a web-based  
monitor built in, so you can simply point your web browser to the monitor's TCP port on  
PowerMTA's machine to view the mailer's current status and display information about  
its queue. This comes particularly handy when monitoring over longer periods of time.  
The web monitor is described in detail in Chapter 5.  
The same information from the web monitor also available through the pmta command  
line tool. In addition to displaying the command results in formatted plain text, pmtacan  
also output these in XML or as DOM-Style variable lists, making it relatively easy to  
post-process and to integrate PowerMTA in existing management infrastructures. The  
pmtacommand line tool and the commands it accepts are described in Chapter 6.  
4.1.2 Logging and Accounting  
For greatest flexibility and best performance, PowerMTA maintains its own logging file.  
The operating system's log (i.e., the Event Log on Windows NT/2000 or the "syslog" on  
Unix) is only used for recording information on startup errors and similar situations  
where it may not be possible for PowerMTA to write to its own logging file.  
The logging file is used for recording various information about PowerMTA, such as  
startup and shutdown messages, any errors found during execution, connection traces,  
etc. In general terms, the log file is the place where the mailer writes any error messages,  
and you should look there first when any problems arise.  
In addition to the logging file, PowerMTA records detailed information on e-mails  
processed in a separate accounting file. Storing accounting data separate from other, more  
general, logging data allows for a more efficient (binary) accounting file format while  
retaining the logging file in plain text. It also makes it easier to send feedback about  
problems with PowerMTA while keeping the accounting data undisclosed. Section 11  
131  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
       
describes the format of the accounting files, as well as a sample accounting statistics  
application provided with PowerMTA.  
Both logging and accounting files are rotated automatically, that is, a new file is started  
and the older ones are kept for a number of days. On Linux systems, this is done by  
automatically extending the logrotate configuration to include PowerMTA's files. On  
Windows NT/2000 and Solaris, this is implemented in PowerMTA itself. The parameters  
for the rotation, including the number of (historical) files to keep can are described in  
Section 3.2.6 and in Section 3.2.7.  
4.1.3 PowerMTA Startup and Shutdown  
On Windows NT/2000 systems, PowerMTA runs as a service and as such is started up  
automatically by the operating system after booting. It also can be started and stopped  
both via the Control Panel and by using the net start pmta and net stop pmta  
commands from a Command Prompt window. Currently, PowerMTA must run under the  
SYSTEMaccount.  
On Unix systems, PowerMTA runs as a daemon, i.e., a background process. A standard  
startup/shutdown script is provided in the system's init.ddirectory.  
On either platform, two processes are started: pmtad, which is PowerMTA itself, and  
pmtawatch, which is PowerMTA's watchdog process. As the name suggests, pmtawatch  
watches over PowerMTA and re-starts it in case of a (PowerMTA) crash.  
4.2 Troubleshooting  
The following sections guide through troubleshooting the most commonly encountered  
problems.  
4.2.1 Troubleshooting Startup Problems  
Startup problems typically occur right after installing PowerMTA or after having  
changed its configuration. If PowerMTA won't start up, you should look in the logging  
file for an error message. On Windows NT/2000, the logging file is named log.txtand  
is located in the logsubdirectory of the folder where PowerMTA was installed. On Unix  
systems, the logging file is located on /var/log/pmta/log.  
If no logging file is present or if it does not seem to contain an applicable error message,  
you can try running PowerMTA on the command line. On Windows NT/2000, open a  
Command Prompt window and change to PowerMTA's bin subdirectory. On Unix,  
ensure that /usr/sbinis in your path. Then start PowerMTA by using the command  
132  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
pmtad --debug  
That will start up PowerMTA and will have it write any error messages to the screen,  
rather than to the logging file. Most probably, the startup will fail displaying an error  
message, like in the example below:  
# /usr/sbin/pmtad --debug  
2000-07-03 18:05:37 Startup error: No logging file specified  
You can then fix the problem and re-start it. If PowerMTA does start, you can shut it  
down by simply pressing Control-C once and waiting for it to stop. On Windows  
NT/2000, pressing Control-C repeatedly causes it to do an "emergency exit". On Unix,  
you can achieve a similar effect by pressing Control-\ (thus sending it the SIGQUIT  
signal). Use the emergency exits only if absolutely necessary (e.g., if the mailer won't  
shut down after waiting for several minutes), since it may cause PowerMTA to loose  
track of which recipients have already been handled, causing duplicate deliveries.  
A common cause of startup problems when PowerMTA is first installed is TCP port  
conflicts. Applications that listen for (i.e., accept) connections on a TCP port need  
exclusive access to the port, so if you are running other SMTP server software on the  
same machine, either PowerMTA or the other software will fail to obtain access to port  
number 25 (the standard port for the SMTP protocol). The same might also happen with  
the TCP port used for the built-in web monitor (port 8080 by default). In the case of the  
the web monitor, since 8080 is just a local convention, you can resolve the conflict by  
changing the configuration (see Section 3.2.5) and specifying the new port in your web  
browser.  
The SMTP port conflict may be more difficult to solve. If you are not using PowerMTA  
for handling inbound traffic, i.e., you are just feeding PowerMTA through SMTP or the  
submission APIs and inbound traffic is handled by some other software, you can  
configure PowerMTA to use an alternative SMTP port (see Section 3.2.4) and change  
your feeding software to use that port. You can normally pick any free TCP port above  
1024; port numbers 2500 and 2525 are popular choices.  
If, on the other hand, both PowerMTA and the other SMTP server software are to receive  
inbound traffic, you will need to give each of them a different IP address. Normally,  
applications listening for (i.e., accepting) connections on a TCP port will do so for all  
locally available IP addresses, so both PowerMTA and the other SMTP software need to  
be configured to use a specific IP address only (see Section 3.2.4 for PowerMTA's  
configuration). Naturally, you will first need to allocate a new IP address and configure  
your operating system to respond to it.  
133  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
4.2.2 Troubleshooting E-mail Delivery Problems  
E-mail delivery problems constitute by far the most common type of problem  
encountered. It is quite normal for some e-mail not to be delivered immediately and for  
the delivery to have to be retried. The causes of such problems are often invalid e-mail  
addresses, network or server failures or misconfigured software at the recipient's site.  
If you notice e-mail building up in the queue for a specific domain, the first step is to  
check the (DNS-based) routing information for the domain. If that information is  
available and seemingly correct, the next step would be to check whether any of the listed  
mailers is reachable. PowerMTA's pmtacommand line tool has a resolvecommand that  
allows you to do all of that in a single step:  
$ pmta resolve --connect hotmail.com  
Querying 193.175.161.130 over UDP about MX(15) hotmail.com  
status = StatusOk (no error)  
pref- host name--------------------- IP addresses/resolution status----  
--------  
10 mc2.law5.hotmail.com  
10 mc4.law5.hotmail.com  
10 mc5.law5.hotmail.com  
10 mail.hotmail.com  
216.32.243.135  
216.33.151.136  
216.32.243.136  
216.33.151.135  
Connecting to mc2.law5.hotmail.com (216.32.243.135)... ok  
>>> 220-HotMail (NO UCE) ESMTP server ready at Tue Jul 04 08:02:57 2000  
>>> 220 ESMTP spoken here  
<<< ehlo test  
>>> 250-hotmail.com Hello  
>>> 250 SIZE 1048576  
<<< quit  
>>> 221 Service closing transmission channel  
In the example above, routing information for the domain hotmail.com could be  
resolved. It listed four mail hosts, all with preference level 10, each with its own IP  
address. The --connect option specified that pmta attempts connecting to the mailers  
(which it did, to "mc2").  
When you enter this command during troubleshooting, either part of the command may  
fail. You may get an error during the DNS resolution part, like, for example "No such  
domain name" for a domain that is not registered in the DNS. Similarly, if the routing  
information is available but if the mailers themselves are not reachable, the connection  
attempt fails.  
Simply connecting to the mailers does not preclude other problems delivering e-mail, for  
the problem may be related to the specific messages queued, or the mailers may be  
temporarily rejecting e-mail (e.g., returning a 4XX code to SMTP commands). To verify  
134  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
if this is happening, use the pmta trace command. As described in Section 6.3.21, the  
tracecommand instructs PowerMTA to retry e-mail delivery to the domain immediately  
and log the connection. This way, you can see (in the logging file) exactly what happens  
when delivery is attempted.  
The pmta trace command is useful for quickly checking on a domain. If you should  
need to trace connections to a domain over a longer period of time, enable logging for it  
in the configuration file by adding a <domain>entry, like in in the example below:  
<domain hotmail.com>  
log-connections yes  
log-commands yes  
</domain>  
Please remember to add such domain-specific entries before the <domain *> entry  
present in most configuration files and to reload the configuration by using pmta reload.  
4.2.3 Troubleshooting DNS Name Resolution  
Problems  
PowerMTA requires a recursive name service, i.e., a name server that accepts queries and  
performs the full DNS resolution on its behalf.  
Some name servers fail to do the recursive lookup and return non-recursive (referral-  
only) responses instead. These responses don't contain the information sought by  
PowerMTA, so it discards them and retries the query in the hope that whatever caused  
them is temporary, or that some other server will provide the full response. When such  
responses are received a number of times from the same name server, PowerMTA also  
writes a warning to its logging file.  
Generally speaking, such non-recursive responses may have various causes. However,  
some DNS server software versions are known to send them when configured to refuse  
recursive service, or when its limit of concurrent recursive queries has been reached.  
Non-recursive responses waste time and may have an impact on performance. If you find  
a name server refusing recursive queries too often, check the name server configuration  
for any quotas or access control lists. If you do not control the name server, you should  
consider no longer using it for PowerMTA and setting up your own.  
135  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
4.2.4 Troubleshooting E-mail Reception/SMTP  
Feeding Problems  
Problems receiving e-mail are quite rare and happen most commonly when writing  
custom applications to feed PowerMTA. The most common mistake when writing such  
applications is to terminate lines with just a line feed, rather than a carriage return and  
line feed pair as mandated by the e-mail standards.  
The simplest way to debug incoming SMTP connections into PowerMTA is to enable  
debugging for a specific source IP address. You do so by adding a <source>entry in the  
configuration file, like in the example below,  
<source 127.0.0.1>  
log-connections yes  
log-commands yes  
</source>  
and reload the configuration by using the pmta reload command. This will cause  
PowerMTA to trace incoming connections to the logging file, which helps determine in  
what phase of the transaction (for example, in a RCPT command) the problem is  
occurring. If you suspect the problem to lay in non-printable characters or in the  
message's body, you can additionally enable log-data, which prints all data sent or  
received through the connection along with each byte's hexadecimal code. For more  
information on the logging options available, please see Section 3.2.6.  
4.2.5 In Case of a Crash  
If PowerMTA crashes, its pmtawatch watchdog program will attempt to re-start it and  
you should get an e-mail informing you about the crash. Please forward this e-mail to us  
at support@port25.com, so that we can look into the problem. Feel free to include any  
information you may find relevant, such as recent changes to the configuration or  
workload, etc.  
On Unix systems, the core dump will be stored, compressed if possible, in PowerMTA's  
subdirectory on the /optfilesystem.  
4.2.6 If All Else Fails  
Check out http://www.port25.com/support/ for technical support options from Port25.  
Evaluators and customers with a support agreement may also get support via e-mail at  
support@port25.com or over the phone at +1.410.203.2323.  
136  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
5. Web-Based Monitoring  
5.1 Overview  
PowerMTA has a web-based monitoring console built in that provides real time display  
of PowerMTA's status and allows you to view information on the current message queue  
based on various criteria. The idea is to continue to develop this monitor into a full-blown  
management console. This chapter describes the functionality implemented to date.  
To access the web monitor, point your web browser to the monitor's TCP port on the  
machine you installed PowerMTA. For example, if you are reading this document online  
and from the same machine running PowerMTA, you would use the URL  
http://127.0.0.1:8080. This also assumes that you did not change the default TCP port in  
the configuration. See Section 3.2.5 for more information on the web monitor's  
configuration.  
When you try the URL, you may get a message saying that the access is forbidden. This  
is because, to protect your privacy, access to the web monitor is denied unless authorized  
in the configuration. Authorization is done on a per source IP address basis, so you need  
to enter the IP address of the host running your web browser into the configuration.  
137  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
5.2 Home Display  
The initial "Home" page displays basic information about your installation. In addition to  
this information, there are four useful links:  
Edit Configuration – This allows you to view and edit the configuration file from  
within the web monitor window. After saving changes, a “pmta reload” will not  
be required as it it done automatically. If the change requires a restart of the  
service, that will have to be done manually.  
Show/enter License Key – This links to a form where you can view/add/change  
the license.  
Run command – This link allows you to run “pmta” commands as if you were  
logged in a the command/shell prompt of the PowerMTA server.  
User’s Guide – Opens UserGuide.pdf in a new window for ease of looking up  
PowerMTA information.  
Port25 Support – Starts an email to support @port25.com using your default  
email program.  
138  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
From the home page, you have the option of changing to other displays:  
Status, the status monitor page, which displays various information about  
PowerMTA's status, updated every few seconds;  
Queues, which presents you with various options for listing queues to which e-  
mail is queued.  
Domains, which presents you with various options for listing domains to which e-  
mail is queued.  
VirtualMTAs, which displays a summary of the VirtualMTAs in use;  
Jobs, which presents you with summary information on any jobs (groups of  
messages) queued.  
Logs, allos for the viewing and downloading of PowerMTA’s various log files.  
The following sections describe these pages in more detail.  
139  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
5.3 Status Monitor Display  
The status monitor displays data from various components within PowerMTA.  
The "Total" counters show the total data received and sent since the mailer was started.  
Similarly, the "Last Hour" and "Last Minute" counters show the total data received and  
sent for the respective time intervals. Note that this has been changed from the earlier  
beta versions which extrapolated the data up to the time increment if the mailer had not  
been running for a full hour or full minute.  
140  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
The "Top/Hour" and "Top/Minute" lines show the highest throughput observed per hour  
and minute. The various counters are measured independently of each other, i.e., the top  
number of inbound recipients may or may not have happended at the same time as the top  
number of inbound kbytes.  
The "Connections" section shows the number of currently active connections, the top  
number of simultaneous connections made since last restart, and the maximum number of  
inbound and outbound simultaneous connections available given your license activation  
key and configured limits.  
The "Domain Names" section shows the number of DNS entries currently in  
PowerMTA's internal cache, as well as the number of DNS queries pending, i.e.,  
currently taking place or scheduled and waiting to take place.  
The "Spool Files" section shows the number of spool files currently being used for  
storing queued messages. And, since the spool management code recycles files for  
efficiency instead of having to recreate as needed, this section also tracks the number of  
files that have been recycled and are waiting to be reused.  
The "Spool Initialization" section shows whether the initialization is in progress or has  
been completed. This initialization takes place at startup and consists of reading the  
message files in the spool and loading queue information into memory.  
The "Queues" section provides top level counts for each of the delivery methods  
available: SMTP or through the pipe delivery API. The counts include the total number  
of recipients currently in the queue, total number of destination domains for these  
recipients, and the total amount of data in the mail queues to be delivered, for each  
method.  
The default refresh interval is five seconds. You can select a different refresh interval by  
specifying a refreshparameter in the URL. For example, to specify a refresh interval of  
five  
minutes  
(300  
seconds),  
you  
could  
use  
an  
URL  
like  
http://127.0.0.1:8080/status?refresh=300. The refresh interval is independent of the  
internal throughput sampling interval, and as such has no effect on the display's accuracy.  
It thus normally makes little sense to specify refresh intervals below the default.  
Specifying refresh intervals above the default interrupts PowerMTA less often, which  
may have a positive impact on performance.  
This page can also be retrieved in XML format for processing by a program. You specify  
the XML format by adding format=xml to the URL. For example, you could use the  
wgetutility to retrieve it:  
$ wget -O- -q http://127.0.0.1:8080/status?format=xml  
<rsp><data><mta><product><name>PowerMTA</name><version>2.0r1</version>  
<buildDate>Jun 30 2003 19:15:23</buildDate></product><os><name>Linux</name>  
<version>2.4.18-10</version><build>Red Hat Linux release 7.3 (Valhalla)</build>  
141  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
</os><cpu><type>i686</type><count>1</count></cpu><ram><real>513800</real></ram>  
<fullHostName>hazmat.port25.com</fullHostName><userString></userString></mta>  
<status><timeNow>1031828706</timeNow><startupTime>1031815851</startupTime>  
<shuttingDown>0</shuttingDown><traffic><total><out><rcp>1</rcp><msg>1</msg>  
<kb>1.7</kb></out><in><rcp>1</rcp><msg>1</msg><kb>1.6</kb></in></total>  
<lastHr><out><rcp>1</rcp><msg>1</msg><kb>1.7</kb></out><in><rcp>1</rcp>  
<msg>1</msg><kb>1.6</kb></in></lastHr><lastMin><out><rcp>0</rcp><msg>0</msg>  
<kb>0.0</kb></out><in><rcp>0</rcp><msg>0</msg><kb>0.0</kb></in></lastMin>  
<topPerHr><out><rcp>1</rcp><msg>1</msg><kb>1.7</kb></out><in><rcp>1</rcp>  
<msg>1</msg><kb>1.6</kb></in></topPerHr><topPerMin><out><rcp>1</rcp>  
<msg>1</msg><kb>1.7</kb></out><in><rcp>1</rcp><msg>1</msg><kb>1.6</kb></in>  
</topPerMin></traffic><conn><smtpIn><cur>0</cur><max>30</max><top>0</top>  
</smtpIn><smtpOut><cur>0</cur><max>800</max><top>1</top></smtpOut></conn>  
<resolver><namesCached>5</namesCached><queriesPending>0</queriesPending>  
</resolver><queue><smtp><rcp>0</rcp><dom>0</dom><kb>0.0</kb></smtp></queue>  
<spool><initPct>100</initPct><dirs>1</dirs><files><inUse>0</inUse>  
<recycled>1</recycled><total>1</total></files></spool></status></data></rsp>  
142  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
5.4 Queues Display  
Similar to the "Top Domains" page, the "Top Queues" page provides a listing of the top  
ten queues ranked by number of recipients.  
For greatest flexibility and control, PowerMTA groups messages for a particular domain  
for a particular VirtualMTA in its own separate queue. For example, mail destined for  
msn.com and handled by VirtualMTA mta5 would be in a different queue than mail  
destined for msn.comand handled by VirtualMTA mta10.  
Whereas the "Top Domains" page provides a global view with the top ten domains across  
all queues, the "Top Queues" page provides a listing and counts for specific queues.  
5.5 Queues “View Options”  
The "Queues" page consists of a Queues “view options" form which after submitting,  
generates an output similar in format to the "Top Queues" page, but for the specific  
queue(s) specifed in conjunction with relevant filters.  
143  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
The filters include:  
connected queues only, unconnected queues only, or both  
queues in normal mode, backoff mode, or any mode  
the desired number of queues to list  
One can then choose how to sort the output, either by queue name, number of recipients,  
or queue size.  
144  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
5.6 Domains Display  
The "Top Domains" page provides a listing of the top ten domains in the queue ranked by  
number of recipients.  
For each domain listed, the number of the number of recipients, amount of data (kbytes),  
the number of open connections and the last error occurred while delivering to the  
domain are displayed.  
Because this page is relatively resource intensive to build, the default refresh interval is  
two minutes. You can select a different refresh interval by specifying a refresh  
parameter in the URL. Additionally, you can also request that more domains be displayed  
by entering a maxItems parameter. For example, to specify a refresh interval of five  
minutes (300 seconds) and twenty top domains, you could use an URL like  
http://127.0.0.1:8080/topdomains?refresh=300&maxItems=20.  
145  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
5.7 Domains “View Options”  
The "Domains" page consists of a Domains “view options" form which after submitting,  
generates an output similar in format to the "Top Domains" page, but for the specific  
domain(s) and based on the other parameters specifed.  
5.8 Common "Last Error"s  
Included below is a list of the most common "Last Error" messages, with an explanation  
about what may cause them. On Windows NT/2000, system status codes may be prefixed  
with WSA, but indicate generally the same condition.  
ETIMEDOUT in connection to domain (IP)  
This error indicates that the connection failed because, while connected, the  
remote host did not properly respond within a period of time. It possibly indicates  
that the remote host is overwhelmed or that there are connectivity problems.  
PowerMTA's connection timeout parameter is 10 minutes, and is not  
configurable.  
ECONNREFUSED connecting to domain (IP)  
This error indicates that no connection could be made because the remote host  
actively refused it. This usually results when the remote mailer software is  
temporarily down or inactive, or if the remote site is actively refusing connections  
(usually with a packet filter) from your company and/or IP address.  
EDISCON in connection to domain (IP)  
This error indicates that the remote host has unexpectedly closed the connection.  
It may result from the remote mail server being taken down, crashing, or simply  
closing the connection, possibly as a "last resort" kind of response to message  
contents it could not process.  
StatusDnsQueryFailed resolving domain  
146  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
This error indicates that the DNS query for the domain could not be completed.  
This could be due to more than one reason, specifically timeouts when  
PowerMTA attempts to talk to your local DNS server, but more likely, timeouts  
in your local DNS server itself when attempting to talk to other DNS servers.  
Although these errors can and will be seen for some domains that appear to not  
have valid MX or A records, the fact that the actual DNS queries timeout before  
receiving any verification of this precludes PowerMTA from making any  
assumptions and thus, for example, bouncing mail to these domains immediately.  
EHLO failed  
These are errors that are returned by the remote mail server during the initial  
SMTP handshake (at the HELO or EHLO SMTP commands). Usually the text  
included in the error messages is self-explanatory. Here are a few examples:  
421 domain Service not available - too busy  
421 domain Sorry, you are not authorized to make this connection.  
421 domain temporarily not accepting mail  
452 domain Too busy, please try later.  
In order to avoid filling its limited space with irrelevant errors, PowerMTA is quite  
selective about which events it records.  
If you see domains in the queue with no errors specified, along with no active  
connections, this means that the error(s) occurred during the last attempt is not among  
those events that PowerMTA records. For these domains, we recommend running the  
trace command from the command line interface, as detailed Section 6.3.21, or enable  
one or more of the various types of logging available as detailed in Section 3.2.6.  
As we continue to improve upon this feature, more events and error conditions will be  
recorded.  
147  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
5.9 VirtualMTAs Display  
The VirtualMTAs page provides a listing of the VirtualMTAs selected that currently have  
messages in the queue. The VirtualMTAs are listed sorted by number of recipients.  
Each VirtualMTA listed also links to a top domains page that subsequently lists the top  
10 domains in the queue for the specific VirtualMTA, ranked by number of recipients in  
the queue. Also included on this page is the volume of data in the queue, number of  
148  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
current connections open to the domain, and the last error received for the domain, again  
for the specific VirtualMTA.  
5.10 Jobs Display  
For each job listed, the number of the number of recipients and amount of data (kbytes)  
are displayed.  
As with most pages served by PowerMTA, you can specify a refresh interval in seconds  
by adding it to the URL. For example, to specify a refresh interval of five minutes (300  
seconds), you could use an URL like http://127.0.0.1:8080/jobs?refresh=300.  
Like with the status display, this page can also be retrieved in XML format for processing  
by a program, by adding format=xmlto the URL.  
149  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
5.11 Logs Display  
The Logs page displays the various log and accounting files currently available in  
PowerMTA. By choosing the download link, these files can be downloaded directly to  
your local machine for viewing. In addition, these files can be accessed  
programmatically via the URL format: http://127.0.0.1:8080/getFile?file=log.txt where  
“log.txt” is the name of the file you want to download.  
150  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
5.12 Listing of local IPs  
To get a list of the IPs currently configured on your machine, use the following URL in  
your web browser: http://127.0.0.1:8080/getlocalips  
151  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
5.13 Listing of emails in queue  
To get a listing of the messages that are currently in the queue, use a URL similar to the  
following in your web browser:  
http://127.0.0.1:8080/listqueue?format=xml&queue=domain.com/VirtualMTA&jobid=12  
http://127.0.0.1:8080/listqueue?format=xml&queue=yahoo.com/*&jobid=12&envid=3  
http://127.0.0.1:8080/listqueue?format=xml&queue=*/vmta12&rcpt=test@port25.com  
http://127.0.0.1:8080/listqueue?format=xml&queue=*/*&orig=test@port25.com  
Use of jobid is optional. Replace domain.com with the domain for which you are  
looking. Also replace VirtualMTA with the name of the VirtualMTA in question. Also,  
use * for all domains or all VirtualMTAs.  
152  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
6. Command Line Tool  
6.1 Overview  
PowerMTA comes with a command line tool that allows you to execute commands,  
display various information and also generally aids in investigating delivery problems.  
On Windows NT/2000, this tool can be found under bin\pmta.exe in the folder where  
PowerMTA was installed. On Unix, it is installed as /usr/sbin/pmta. At the command  
line, you can get a quick listing of the commands available by invoking pmta --help:  
PowerMTA(TM) v4.0b1 command tool  
Copyright(c) 1999-2010, Port25 Solutions, Inc. All Rights Reserved.  
Usage: pmta [options] command  
where 'options' are:  
--help  
--xml  
--dom  
display this message  
display result in XML  
display result as DOM-like "variables"  
and where 'command' is one of:  
clear dnscache domainname  
check mfrom [--tcp] [--dumppackets] mailfrom ip  
check pra [--tcp] [--dumppackets] pra ip  
delete [--dsn] [--accounting] [--queue=domain[/vmta]] [--orig=addr] [--rcpt=addr] [--jobId=id] [--envId=id]  
deregister [--user=name]  
list [--queue=domain[/vmta]] [--orig=addr] [--rcpt=addr] [--jobId=id] [--envId=id] [--maxitems=n] [--pause]  
pause queue domain[/vmta]  
register [--user=name] [--label=name] [--webmon-ip=ip] [--webmon-port=number] [--pmta-central-port=number] [--  
reuse-label] pmta-central-hostname  
reload  
reset counters  
reset status  
resolve [--tcp] [--connect] [--dumppackets] [--interactive] [--source=[host,]ip] domainname  
resume queue domain[/vmta]  
rotate acct [file]  
rotate log  
schedule domain[/vmta]  
set queue --mode={normal|backoff} domain[/vmta]  
show domains [--vmta=name] [--connected={yes|no}] [--maxitems=n] [--errors] [--sort={name|rcpt|size}] [name]  
show jobs [--maxitems=n] domain[/vmta]  
show license  
show queues [--connected={yes|no}] [--paused={yes|no}] [--mode={normal|backoff}] [--maxitems=n] [--errors] [--  
sort={name|rcpt|size}] [domain[/vmta]]  
show registration  
show status  
show settings domain[/vmta]  
show topdomains [--vmta=name] [--connected={yes|no}] [--maxitems=n] [--errors]  
show topqueues [--connected={yes|no}] [--paused={yes|no}] [--mode={normal|backoff}] [--maxitems=n] [--errors]  
[domain[/vmta]]  
show version  
show vmtas [--maxitems=n]  
trace [--logdata] [--logresolution] [--to-log] domain[/vmta]  
disable source [--reenable-after=interval] ip domain[/vmta]  
enable source ip domain[/vmta]  
show disabled sources [domain[/vmta]]  
153  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
Note: On Windows NT/2000, you can also use the "/" character instead of "--" (but "--"  
works on all platforms).  
6.2 Command Output Formats  
pmtasupports three output formats:  
formatted plain text, intended for human consumption, i.e, for the system or  
services administrator executing PowerMTA commands. It is the default format if  
no options are passed to pmta.  
XML tags, intended for XML-enabled applications. It is selected by specifying  
the --xmloption to pmta;  
DOM-style variable listing, intended for non XML-capable applications and for  
quick Perl or shell scripts. It is selected by specifying the --domoption to pmta.  
6.2.1 Sample Command Outputs  
Included below are three sample command outputs along with the commands and options  
used to generate each. For comparison purposes, all three are based on the show status  
command.  
Formatted Plain Text (pmta show status):  
PowerMTA v4.0r1 status on test.port25.com on 2011-03-28 12:05:37  
Traffic  
Total  
Last Hour  
Top/Hour  
Last Min.  
Top/Min.  
------------inbound------------ ------------outbound-----------  
rcpts  
msgs  
kbytes  
0.0  
rcpts  
msgs  
kbytes  
0.0  
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0.0  
0.0  
0.0  
0.0  
0.0  
0.0  
0.0  
0.0  
Connections  
Inbound  
active  
top  
0
maximum Domain  
cached  
0
pending  
0
0
0
30  
0
Names  
Outbound  
0
Queues  
SMTP  
other  
rcpts domains  
kbytes Spool  
in use  
0
recycled  
0
complete  
0
0
0
0
0.0  
0.0  
Files  
Init.  
Status  
running  
Started 2008-03-27 14:37:34  
Uptime 0 21:28:03  
XML Format (pmta --xml show status):  
<rsp><data><mta><product><name>PowerMTA</name><version>2.0r1</version>  
<buildDate>May 25 2003 21:24:07</buildDate></product><os><name>Linux</name>  
<version>2.4.20-13.9</version><build>Red Hat Linux release 9 (Shrike)</build>  
</os><cpu><type>i686</type><count>1</count></cpu><ram><real>513292</real></ra  
m>  
154  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
<fullHostName>hazmat.port25.com</fullHostName><userString></userString></mta>  
<status><timeNow>1053890861</timeNow><startupTime>1053890656</startupTime>  
<shuttingDown>0</shuttingDown><traffic><total><out><rcp>0</rcp><msg>0</msg>  
<kb>0.0</kb></out><in><rcp>0</rcp><msg>0</msg><kb>0.0</kb></in></total><lastH  
r>  
<out><rcp>0</rcp><msg>0</msg><kb>0.0</kb></out><in><rcp>0</rcp><msg>0</msg>  
<kb>0.0</kb></in></lastHr><lastMin><out><rcp>0</rcp><msg>0</msg><kb>0.0</kb>  
</out><in><rcp>0</rcp><msg>0</msg><kb>0.0</kb></in></lastMin><topPerHr><out>  
<rcp>0</rcp><msg>0</msg><kb>0.0</kb></out><in><rcp>0</rcp><msg>0</msg>  
<kb>0.0</kb></in></topPerHr><topPerMin><out><rcp>0</rcp><msg>0</msg><kb>0.0</  
kb>  
</out><in><rcp>0</rcp><msg>0</msg><kb>0.0</kb></in></topPerMin></traffic>  
<conn><smtpIn><cur>0</cur><max>30</max><top>0</top></smtpIn><smtpOut>  
<cur>0</cur><max>800</max><top>0</top></smtpOut></conn><resolver>  
<namesCached>0</namesCached><queriesPending>0</queriesPending></resolver>  
<queue><smtp><rcp>0</rcp><dom>0</dom><kb>0.0</kb></smtp><pipe><rcp>0</rcp>  
<dom>0</dom><kb>0.0</kb></pipe></queue><spool><initPct>100</initPct>  
<dirs>1</dirs><files><inUse>0</inUse><recycled>0</recycled><total>7</total>  
</files></spool></status></data><succ></succ></rsp>  
DOM-Style (pmta --dom show status):  
mta.product.name="PowerMTA"  
mta.product.version="2.0r1"  
mta.product.buildDate="May 25 2003 21:24:07"  
mta.os.name="Linux"  
mta.os.version="2.4.20-13.9"  
mta.os.build="Red Hat Linux release 9 (Shrike)"  
mta.cpu.type="i686"  
mta.cpu.count="1"  
mta.ram.real="513292"  
mta.fullHostName="hazmat.port25.com"  
mta.userString=""  
status.timeNow="1053891030"  
status.startupTime="1053890656"  
status.shuttingDown="0"  
status.traffic.total.out.rcp="0"  
status.traffic.total.out.msg="0"  
status.traffic.total.out.kb="0.0"  
status.traffic.total.in.rcp="0"  
status.traffic.total.in.msg="0"  
status.traffic.total.in.kb="0.0"  
status.traffic.lastHr.out.rcp="0"  
status.traffic.lastHr.out.msg="0"  
status.traffic.lastHr.out.kb="0.0"  
status.traffic.lastHr.in.rcp="0"  
status.traffic.lastHr.in.msg="0"  
status.traffic.lastHr.in.kb="0.0"  
status.traffic.lastMin.out.rcp="0"  
status.traffic.lastMin.out.msg="0"  
status.traffic.lastMin.out.kb="0.0"  
status.traffic.lastMin.in.rcp="0"  
status.traffic.lastMin.in.msg="0"  
status.traffic.lastMin.in.kb="0.0"  
status.traffic.topPerHr.out.rcp="0"  
155  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
status.traffic.topPerHr.out.msg="0"  
status.traffic.topPerHr.out.kb="0.0"  
status.traffic.topPerHr.in.rcp="0"  
status.traffic.topPerHr.in.msg="0"  
status.traffic.topPerHr.in.kb="0.0"  
status.traffic.topPerMin.out.rcp="0"  
status.traffic.topPerMin.out.msg="0"  
status.traffic.topPerMin.out.kb="0.0"  
status.traffic.topPerMin.in.rcp="0"  
status.traffic.topPerMin.in.msg="0"  
status.traffic.topPerMin.in.kb="0.0"  
status.conn.smtpIn.cur="0"  
status.conn.smtpIn.max="30"  
status.conn.smtpIn.top="0"  
status.conn.smtpOut.cur="0"  
status.conn.smtpOut.max="800"  
status.conn.smtpOut.top="0"  
status.resolver.namesCached="0"  
status.resolver.queriesPending="0"  
status.queue.smtp.rcp="0"  
status.queue.smtp.dom="0"  
status.queue.smtp.kb="0.0"  
status.queue.pipe.rcp="0"  
status.queue.pipe.dom="0"  
status.queue.pipe.kb="0.0"  
status.spool.initPct="100"  
status.spool.dirs="1"  
status.spool.files.inUse="0"  
status.spool.files.recycled="0"  
status.spool.files.total="7"  
6.3 Command Reference  
6.3.1 clear dnscache  
Syntax:  
pmta clear dnscache domain  
Description:  
This command clears PowerMTA's internal DNS cache, removing all entries for the  
given domain. If the domain is *all cached DNS data is discarded. On Unix the asterisk  
must be escaped with a backslash.  
Example:  
$ pmta clear dns \*  
DNS cache cleared.  
$ pmta clear dns port25.com  
Cleared port25.com from DNS cache.  
156  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
6.3.2 check mfrom  
Syntax:  
pmta check mfrom [--tcp] [--dumppackets] mfrom ip  
Description:  
This command checks whether a message with the given "mfrom" (address in the SMTP  
MAIL FROMcommand, or, if empty, the domain passed in the HELOcommand) would pass  
the Sender-ID check if sent from the given IP address. It is useful to quickly verify SPF  
2.0 records with the "mfrom" scope.  
Options:  
--tcp  
use TCP (rather than the default UDP) for querying the name server(s)  
--dumppackets  
print out an hexadecimal dump of any DNS queries and responses exchanged with  
the name servers. It is ignored unless the output is in text format.  
6.3.3 check pra  
Syntax:  
pmta check pra [--tcp] [--dumppackets] pra ip  
Description:  
This command checks whether a message with the given PRA (Purported Responsible  
Address) would pass the Sender-ID check if sent from the given IP address. It is useful to  
quickly verify SPF 2.0 records with the "pra" scope.  
Options:  
--tcp  
use TCP (rather than the default UDP) for querying the name server(s)  
--dumppackets  
print out an hexadecimal dump of any DNS queries and responses exchanged with  
the name servers. It is ignored unless the output is in text format.  
6.3.4 reload  
Syntax:  
pmta reload  
Description:  
PowerMTA reads its configuration during startup. Use this command to activate the new  
settings after making changes to the configuration file. The reloadcommand is generally  
preferrable to stopping and re-starting PowerMTA because it is more efficient and does  
not cause an interruption in service. However, some of the configuration directives  
cannot be reloaded dynamically and require a restart. See the directive's attributes in  
Section 3.2 to find out whether it is dynamically reloadable.  
157  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
If PowerMTA detects an error in the configuration file, the reload command fails and  
the previous in-memory configuration is retained.  
Example:  
$ pmta reload  
Configuration reloaded.  
6.3.5 reset counters  
Syntax:  
pmta reset counters  
Description:  
PowerMTA performs various statistics based on traffic counters that can can be viewed  
from the web monitor and with the show status command. Normally these statistics  
include all traffic since PowerMTA was started up, but the reset counters command  
allows you to reset these counters without stopping and re-starting PowerMTA. Before  
resetting, PowerMTA saves the counters to the accounting file.  
Example:  
$ pmta reset count  
Traffic counters reset.  
6.3.6 reset status  
Syntax:  
pmta reset status  
Description:  
This command is just an alias to reset counters.  
6.3.7 resolve  
Syntax:  
pmta resolve [--tcp] [--connect] [--dumppackets] [--interactive] [--source=[host,]ip] domainname  
Description:  
The resolve command queries the DNS for mail routing information (MX and A  
records) for the specified domain, displays that information, and optionally connects to  
the first available mailer. It is intended to facilitate tracking down connectivity problems  
to destination domains. For example, if you notice that the queue is building up for a  
specific domain, you can run resolve against that domain to figure out what problems  
exist and what if anything can be done to fix the problem.  
Defaults:  
If no options are specified, DNS resolution is attempted via UDP and any relevant  
information is displayed, however no attempt is made to connect to a mailer.  
Options:  
158  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
--tcp  
this tells PowerMTA to use TCP (rather than the default UDP) for querying the  
name server(s)  
--connect  
this option tells PowerMTA to attempt to connect to the first available mailer as  
well, after querying and displaying the specified domain's DNS server for mail  
routing information.  
--dumppackets  
this option tells PowerMTA to print out an hexadecimal dump of any DNS  
queries and responses exchanged with the name servers. It is ignored unless the  
output is in textual format.  
--interactive  
this option allows the user to try various SMTP commands, to help diagnose  
problems.  
--source  
this option tells PowerMTA form which internal IP address or hostname to  
connect.  
Examples:  
$ pmta resolve --connect hotmail.com  
Querying 192.54.35.100 over UDP about MX(15) hotmail.com  
Querying 192.54.35.100 over UDP about A(1) mc4.law5.hotmail.com  
Querying 192.54.35.100 over UDP about A(1) mc5.law5.hotmail.com  
Querying 192.54.35.100 over UDP about A(1) mc2.law5.hotmail.com  
status = StatusOk (no error)  
pref- host name--------------------- IP addresses/resolution status------------  
10 mc4.law5.hotmail.com  
10 mc5.law5.hotmail.com  
10 mail.hotmail.com  
216.33.151.136  
216.32.243.136  
216.33.151.135  
216.32.243.135  
10 mc2.law5.hotmail.com  
Connecting to mc4.law5.hotmail.com (216.33.151.136)... ok  
>>> 220-HotMail (NO UCE) ESMTP server ready at Tue Jun 27 01:48:47 2003  
>>> 220 ESMTP spoken here  
<<< ehlo test  
>>> 250-hotmail.com Hello  
>>> 250 SIZE 1048576  
<<< quit  
>>> 221 Service closing transmission channel  
$ pmta --dom resolve yahoo.com  
Querying 192.54.35.100 over UDP about MX(15) yahoo.com  
Querying 129.26.8.82 over UDP about MX(15) yahoo.com  
Querying 192.54.35.100 over UDP about A(1) mx1.mail.yahoo.com  
Querying 192.54.35.100 over UDP about A(1) mx2.mail.yahoo.com  
status="StatusOk (no error)"  
host[0].pref="0"  
host[0].name="mx1.mail.yahoo.com"  
host[0].status="StatusOk (no error)"  
host[0].ip[0]="128.11.23.224"  
host[0].ip[1]="128.11.68.143"  
host[0].ip[2]="128.11.68.214"  
host[0].ip[3]="128.11.68.223"  
159  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
host[0].ip[4]="128.11.23.236"  
host[0].ip[5]="128.11.23.247"  
host[0].ip[6]="128.11.23.230"  
host[0].ip[7]="128.11.23.235"  
host[1].pref="1"  
host[1].name="mx2.mail.yahoo.com"  
host[1].status="StatusOk (no error)"  
host[1].ip[0]="128.11.68.148"  
host[1].ip[1]="128.11.23.227"  
host[1].ip[2]="128.11.23.236"  
host[1].ip[3]="128.11.68.145"  
host[1].ip[4]="128.11.23.229"  
host[1].ip[5]="128.11.68.95"  
host[1].ip[6]="128.11.23.230"  
host[1].ip[7]="128.11.68.213"  
6.3.8 rotate acct  
Syntax:  
pmta rotate acct [file]  
Description:  
This command instructs PowerMTA to immediately rotate the accounting file.  
If  
included, only the specified file will be rotated. This is usefull if the only one type of file  
is needed to be rotated (e.g. the binary file or the csv file). Immediate rotation does not  
affect the automatic rotation at midnight, which is still performed.  
Example:  
C:\>C:\pmta\bin\pmta rotate acct  
Accounting file rotated.  
6.3.9 rotate log  
Syntax:  
pmta rotate log  
Description:  
This command instructs PowerMTA to immediately rotate the logging file. Immediate  
rotation does not affect the automatic rotation at midnight, which is still performed.  
Example:  
C:\>C:\pmta\bin\pmta rotate log  
Logging file rotated.  
6.3.10 schedule  
Syntax:  
pmta schedule domain/vmta  
Description:  
160  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
Instructs the mailer to immediately open a connection to the specified domain and to  
attempt delivery of messages queued to it. This command would be used, for example, if  
one figured out and fixed connectivity problems to a site and then wanted to bypass the  
normal retry interval from the configuration file. If there are no entries in the queue for  
the domain specified, the PowerMTA's response says so and it does not connect to the  
domain. A wildcard can also be specified in domain or vmta, allowing multiple  
domains/vmtas to be scheduled at once.  
Options:  
--vmta=name  
specifies the VirtualMTA from which to open the connection. If not specified, all  
VirtualMTAs for which messages are queued are scheduled. Only specific  
VirtualMTAs are accepted (no VirtualMTA pools).  
Example:  
$ pmta schedule "port25.com"  
0 of 0 matching, 0 total domains scheduled.  
6.3.11 set queue  
Syntax:  
pmta set queue --mode={normal|backoff} domain/vmta  
Description:  
Sets the given queue's mode of operation to either normalor backoff. While in backoff  
mode, various different settings may apply. See the backoff-... directives in Section  
3.2.8 for more information.  
Wildcards can be used to modify various queues at the same time, but when used, they  
only apply to queues that contain messages or that are already in backoff mode.  
6.3.12 show domains  
Syntax:  
show domains [--vmta=name] [--connected={yes|no}] [--maxitems=n]  
[--errors] [--sort ={name|rcpt|size}] [name]  
Description:  
This command allows you to view current information on the specified destination  
domain(s).  
Options:  
--vmta=name  
displays only domains information for the given VirtualMTA. The default is to  
display (accumulated) information for all VirtualMTAs, including messages for  
which no VirtualMTA was selected.  
--connected  
displays domains to which PowerMTA has least one open outgoing connection.  
161  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
The default is to display both connected and unconnected domains.  
--maxitems=n  
specifies the maximum number of domains to be displayed in the output. By  
default, 20 domains are displayed.  
--errors  
displays any errors recorded for the domain.  
--sort=key  
sort ouput by key where key may be name to order the domain list alphabetically  
by name, rcpt to order the list by number of recipients or size to order the list by  
volume (kbytes).  
name  
domain name or wildcard specifying the domains about which information is to  
be displayed. If omitted, all domains are displayed (subject to the maxitems  
limit).  
Examples:  
$ pmta show dom  
-----------------------------domain --#rcpt ---kbytes conn last error----------  
test1.port25.com  
test10.port25.com  
test11.port25.com  
test12.port25.com  
test13.port25.com  
test14.port25.com  
test15.port25.com  
test16.port25.com  
test17.port25.com  
test18.port25.com  
test19.port25.com  
test2.port25.com  
test20.port25.com  
test21.port25.com  
test22.port25.com  
test23.port25.com  
test24.port25.com  
test25.port25.com  
test26.port25.com  
test27.port25.com  
7
8
3
13  
3
3
3
52  
3
3
3
3
3
3
3
3
3
3
3
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
30.6  
0
0
0
0
0
0
0
0
0
0 ETIMEDOUT connect...  
0
0
0
0
0
0
0
0
0
0
3
20 of 30 domains shown.  
$ pmta show dom --conn  
0 of 0 matching, 30 total domains.  
6.3.13 show queues  
Syntax:  
show queues [--connected={yes|no}] [--paused={yes|no}]  
[--mode={normal|backoff}] [--maxitems=n] [--errors]  
[--sort= {name|rcpt|size}] [queue] [name]  
Description:  
This command allows you to view current information on the specified queues.  
162  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Options:  
--connected  
displays queues for which PowerMTA has least one open outgoing connection.  
The default is to display both connected and unconnected queues.  
--mode  
displays only queues in the specified mode. The default is to display queues in all  
modes.  
--maxitems=n  
specifies the maximum number of queues to be displayed in the output. By  
default, 20 domains are displayed.  
--errors  
displays any errors recorded for the queue.  
--sort=key  
sort ouput by key where key may be nameto order the queue list alphabetically by  
name, rcpt to order the list by number of recipients or size to order the list by  
volume (kbytes).  
--paused={yes|no}  
allows selecting only paused or running queues for display. By default, both are  
shown.  
queue  
name of the queue(s) to display, in the format domain[/vmta], where domain is  
the destination domain name and vmta is the VirtualMTA. If omitted, both  
domain and vmta default to *(i.e., */*), which matches all queues.  
Examples:  
$ pmta show queue  
------------------------------queue --#rcpt ---kbytes conn ---mode last  
error--  
hazmat.port25.com/mta1  
port25.com  
1
3
2
0.1  
0.6  
0.3  
0 normal  
0 normal  
0 backoff  
port25.com/mta1  
3 of 3 matching queues.  
Note that in the example above, there are two queues for port25.com: one for the default  
VirtualMTA, and another for the mta1VirtualMTA.  
$ pmta show que --mode=backoff  
------------------------------queue --#rcpt ---kbytes conn ---mode last  
error--  
port25.com/mta1  
2
0.3  
0 backoff  
1 of 1 matching queue.  
163  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
6.3.14 show jobs  
Syntax:  
show jobs [--maxitems=n] domain[/vmta]  
Description:  
This command allows you to view the jobs currently in PowerMTA's queue. Jobs are  
groups of messages. You can tell PowerMTA that various messages are in the same job  
by specifying the job ID  
in the x-job header (if feeding through SMTP, you should first enable x-job  
processing -- see Section 3.2.4 for details)  
by specifying an envelope ID in the format pmta-XXXX-...where XXXXis the job  
ID  
by calling setJobIdin the submission API  
You can also get the jobs information in XML format from the web monitor directly. See  
Section 5.2 for details.  
Options:  
--maxitems=n  
specifies the maximum number of queues to be displayed in the output. By  
default, 20 jobs are displayed.  
domain[/vmta]  
name of the queue(s) to display, in the format domain[/vmta], where domain is  
the destination domain name and vmta is the VirtualMTA. If omitted, both  
domain and vmta default to *(i.e., */*), which matches all queues.  
Example:  
$ pmta show jobs  
-----------------------------job-id ----#rcpt ---kbytes  
weeklyNews22100  
431  
1236.9  
Total of 1 job(s).  
6.3.15 show settings  
Syntax:  
show settings domain[/vmta]  
Description:  
This command allows you to view the (per-queue) settings for the specified domain and  
VirtualMTA.  
Examples:  
$ pmta --dom show settings port25.com  
allow-cancel-during-transfer="yes"  
auth-password=""  
164  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
auth-username=""  
backoff-max-msg-per-hour="unlimited"  
backoff-notify="no"  
backoff-reroute-to-virtual-mta=""  
backoff-retry-after="1h"  
bounce-after="1d"  
bounce-upon-5xx-greeting="yes"  
bounce-upon-pix-transfer-failure="no"  
bounce-upon-transfer-failure="no"  
command=""  
connect-timeout="2m"  
data-send-timeout="3m"  
queue-priority="50"  
file-destination=""  
file-format="newfile-plain"  
ignore-8bitmime="no"  
log-commands="no"  
log-connections="no"  
log-data="no"  
log-resolution="no"  
log-transfer-failures="no"  
max-events-recorded="10"  
max-msg-per-connection="0"  
max-msg-per-hour="unlimited"  
max-rcpt-per-message="1000"  
max-smtp-out="20"  
pix-bug-workaround="yes"  
retry-after="10m"  
route=""  
smtp-pattern-list=""  
type="file"  
6.3.16 show status  
Syntax:  
pmta show status  
Description:  
Displays a snapshot of what is currently and has previously taken place within the mailer  
since last restart. Intended for a allowing a "quick look" into the general status. The  
output includes totals, top throughput and queue information among other things. The  
output is equivalent to the data available via the web-based monitoring console. You can  
also get the same information in XML format from the web monitor directly. See Section  
5.2 for details.  
165  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Example:  
$ pmta show st  
PowerMTA v2.1a5 status on hazmat.port25.com on 2003-05-25 21:26:48  
Traffic ------------inbound------------ ------------outbound-----------  
Total  
rcpts  
msgs  
kbytes  
0.0  
rcpts  
msgs  
kbytes  
0.0  
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
Last Hour  
Top/Hour  
Last Min.  
Top/Min.  
0.0  
0.0  
0.0  
0.0  
0.0  
0.0  
0.0  
0.0  
Connections  
Inbound  
active  
top  
0
maximum Domain  
cached  
0
pending  
0
0
0
30  
Names  
Outbound  
0
800  
Queues  
SMTP  
other  
rcpts domains  
kbytes Spool  
in use  
0
recycled  
0
complete  
0
0
0
0
0.0  
0.0  
Files  
Init.  
Status  
running  
Started 2003-05-25 21:24:16  
Uptime 0 0:02:32  
6.3.17 show topdomains  
Syntax:  
pmta show topdomains [--vmta=name] [--connected={yes|no}]  
[--maxitems=n] [--errors]  
Description:  
For displaying the top domains in the queue sorted by number of recipients. Since this  
command is equivalent to show domains --sort=rcpt, please see Section 6.3.12 for  
more information on the various options.  
6.3.18 show topqueues  
Syntax:  
show topqueues [--connected={yes|no}] [--mode={normal|backoff}]  
[--maxitems=n] [--errors] [--paused={yes|no}] [domain[/vmta]  
Description:  
For displaying the top queues sorted by number of recipients. Since this command is  
equivalent to show queues --sort=rcpt, please see Section 6.3.13 for more  
information on the various options.  
6.3.19 show version  
Syntax:  
pmta show version  
Description:  
Displays PowerMTA's version and build date.  
166  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
Example:  
$ pmta show ver  
PowerMTA v2.0r1, built on Jun 27 2003 18:36:16.  
6.3.20 show vmtas  
Syntax:  
show vmtas [--maxitems=n]  
Description:  
This command displays a summary of the VirtualMTA(s) in use, as well as the number of  
recipients and kilobytes in messages which select it.  
Options:  
--maxitems=n  
specifies the maximum number of queues to be displayed in the output. By  
default, 20 vmtas are displayed.  
Example:  
$ pmta show vmtas  
-------------------------------name ----#rcpt ---kbytes  
mta1  
mta2  
4
2
0.3  
0.1  
Total of 2 virtual MTA(s).  
6.3.21 trace  
Syntax:  
pmta trace [--logdata] [--logresolution] [--to-log] domain/vmta  
Description:  
Instructs the mailer to open a connection to the specified domain and to attempt delivery  
of any messages queued to it. This command is similar to the schedule command, with  
the difference that it also automatically enables logging for the domain for the duration of  
one connection. If the –to-log switch is used, it is a shortcut to enabling logging in the  
configuration file, reloading the configuration, scheduling a call and undoing these  
changes when debugging is finished. By default, only the SMTP commands and  
responses are logged. The result of this command is written to the logging file.  
Options:  
--logdata  
this enables logging of data transfers as well, like the log-data option in the  
configuration file.  
--logresolution  
this enables logging of the DNS resolution as well, like the log-resolution  
option in the configuration file.  
--to-log  
this enables logging trace info to the log file  
167  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
domain[/vmta]  
name of the queue(s) to display, in the format domain[/vmta], where domain is  
the destination domain name and vmta is the VirtualMTA. If omitted, both  
domain and vmta default to *(i.e., */*), which matches all queues.  
Example:  
$ pmta trace yahoo.com  
Traced connection scheduled (see logging file).  
Logging file output:  
2003-06-27 14:03:10 (402)starting yahoo.com  
2003-06-27 14:03:10 (402)connecting to mx1.mail.yahoo.com (128.11.68.141)  
2003-06-27 14:03:11 (402)>>> 220 YSmtp mta26.mail.yahoo.com ESMTP service ready  
2003-06-27 14:03:11 (402)<<< EHLO hazmat.port25.com  
2003-06-27 14:03:11 (402)>>> 250-mta26.mail.yahoo.com  
2003-06-27 14:03:11 (402)>>> 250-8BITMIME  
2003-06-27 14:03:11 (402)>>> 250-SIZE 3145728  
2003-06-27 14:03:11 (402)>>> 250 PIPELINING  
2003-06-27 14:03:11 (402)<<< QUIT  
2003-06-27 14:03:11 (402)>>> 221 mta26.mail.yahoo.com  
2003-06-27 14:03:11 (402)done yahoo.com in=155 out=30  
6.3.22 delete  
Syntax:  
pmta delete [--dsn] [--queue=domain[/vmta] [--orig=addr] [--rcpt=addr]  
[--jobId=id] [--envId=id] [--accounting]  
Description:  
Deletes recipients from the queue. Although "--queue"'s default is */*, the command  
requires either --queue or --jobId to be entered explicitly, so that an accidental "pmta  
delete" command doesn't delete the entire queue. Messages are marked in the accounting  
file as deleted by administrator.  
Options:  
--dsn  
specifies that a DSN report should be sent. Using this option may slow the  
deletion process. No entry is written to the accounting file unless the --accounting  
flag is used as well.  
--queue  
specifies which queue(s) to delete from, and defaults to all queues.  
--jobId  
specifies that only recipients with the given Job ID are to be deleted  
--envId  
specifies that only recipients with the given Envelope ID are to be deleted.  
--accounting  
specifies that deletion information should be written to the accounting file. Using  
this option may slow the deletion process.  
168  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Example:  
$ pmta delete –-queue=yahoo.com/*  
6.3.23 pause  
Syntax:  
pmta pause queue domain[/vmta]  
Description:  
Pause delivery of messages in the queue, and holds them from being delivered. May be  
run prior to injecting mail into PowerMTA so that mail may be held for later delivery.  
Example:  
$ pmta pause queue */customer1  
6.3.24 resume  
Syntax:  
pmta resume queue domain[/vmta]  
Description:  
Resumes delivery of messages in the queue.  
Example:  
$ pmta resume queue */customer1  
6.3.25 list  
Syntax:  
pmta list [--queue=domain[/vmta]] [--orig=addr] [--rcpt=addr]  
[--jobId=id] [--envId=id] [--maxitems=n] [--pause]  
Description:  
Allows listing recipients from the command line.  
Example:  
$ pmta list --queue=yahoo.com/vmta1  
169  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
6.3.26 license  
Syntax:  
pmta show license  
Description:  
Allows listing license information from the command line.  
Example:  
$ pmta show license  
product: PowerMTA  
version: 3.5  
platform: linux-intel  
units: 0  
options:  
licensee: Acme Corp.  
serial: 123456789  
comment:  
issued: 2008-03-26  
expires: 2008-04-36  
copyright: Port25 Solutions, Inc. All Rights Reserved  
6.3.27 deregister  
Syntax:  
pmta deregister [--user=name] [--local-only]  
Description:  
Allows de-registering a node for PowerMTA Management Console. This command will  
delete all data that has not yet been loaded into PowerMTA Management Console. This  
does not effect the user configured accounting files.  
Options:  
--user  
specifies the PowerMTA Management Console user account to use when  
deregistering  
--local-only  
only dergisters locally, registration will still exist in PowerMTA Management  
Console.  
Example:  
$ pmta deregister  
Deregistration successful.  
You may still need to remove this PowerMTA node manually from  
PowerMTA Management Console.  
170  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
6.3.28 register  
Syntax:  
pmta register [--user=name] [--label=name] [--webmon-ip=ip] [--  
webmon-port=number]  
[--pmtamc-port=number]  
[--reuse-label]  
pmtamc-hostname  
Description:  
Allows registering a node for PowerMTA Management Console  
Options:  
--user  
PowerMTA Management Console user to be used for registration  
--label  
Name of PowerMTA instance that will be shown in PowerMTA Management  
Console  
--webmon-ip  
IP address for PowerMTA Management Console to connect to PowerMTA  
instance  
--webmon-port  
Port for PowerMTA Management Console to connect to PowerMTA instance  
--pmtamc-port  
PowerMTA Management Console port to be used for registration  
--reuse-label  
If label was previously used, but deregistered, this allows label to be used again  
--pmtamc-hostname  
PowerMTA Management Console server to be used for registration  
Example:  
$ pmta register –label=pmta1server central.yourdomain.com  
PowerMTA Management Console "admin" password:  
Registration successful.  
PowerMTA Management Console certificate fingerprint:  
0B:1D:EC:9C:8F:20:4E:06:55:2C:A8:9B:A1:A6:05:C7:DD:07:93:01  
For best security, please verify that the above value is the same as  
the one displayed on PowerMTA Management Console's PowerMTA  
Management page.  
171  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
6.3.29 show registration  
Syntax:  
pmta show registration  
Description:  
Shows current PowerMTA Management Console registration informaiton.  
Example:  
$ pmta show registration  
Currently registered with PowerMTA Management Console  
cental.yourdomain.com:8181 as "pmta1server"  
PowerMTA Management Console certificate fingerprint:  
0B:1D:EC:9C:8F:20:4E:06:55:2C:A8:9B:A1:A6:05:C7:DD:07:93:01  
6.3.30 disable source  
Syntax:  
pmta disable source [--reenable-after=interval] ip domain[/vmta]  
Description:  
Disables a given source IP from being used.  
Example:  
$ pmta disable source --reenable-after=1h 1.2.3.4 yahoo.com/vmta1  
6.3.31 enable source  
Syntax:  
pmta enable source ip domain[/vmta]  
Description:  
Enables a given source IP so it can be used.  
Example:  
$ pmta enable source 1.2.3.4 yahoo.com/vmta1  
172  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
6.3.32 show disabled sources  
Syntax:  
pmta show disabled sources [domain[/vmta]]  
Description:  
Shows currently disabled source IPs.  
Example:  
$ pmta show disabled sources yahoo.com/vmta1  
173  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
7. Application Programming Interfaces  
PowerMTA includes various programming interfaces (APIs) intended to facilitate the  
creation of e-mail enabled applications and to optimize the way in which messages are  
submitted to the mailer. The following APIs are available:  
submission APIs, for submitting e-mail from Perl, Java, .NET, C++ and C  
programs;  
a "pickup" directory, for submitting preformatted e-mail by copying it into a  
directory;  
"pipe" delivery, for delivering e-mail to a local program;  
The Cold Fusion tag from previous PowerMTA versions has been removed, see Section  
7.6 below for details.  
Use of the APIs may require the use of the always-allow-api-submission directive. See  
Section 3.2.13 for more information.  
On Windows NT/2000, any applicable API materials can be found in the api  
subdirectory within the folder into which PowerMTA was installed. On Linux, these can  
be found on /opt/pmta/apiand on Solaris, on /opt/PT25pmta/api.  
7.1 Submission APIs  
The submission APIs allow you to programatically submit messages for delivery by  
PowerMTA. Since most users already have preformatted messages to send, the APIs  
mostly concern themselves with the transport of such messages. However, they do  
include a Date: header generator and a base64 encoder to facilitate the jobs of those  
creating messages from scratch.  
The submission APIs are object-oriented and comprise three objects:  
a Connectionwhich represents a connection to a PowerMTA server;  
a Messagewhich represents the message being submitted;  
a Recipientwhich represents the message's recipients.  
The general procedure for submitting a message is pretty straightforward:  
connect to a PowerMTA server by creating a Connection;  
create a Message;  
create one or more Recipients and add them to the Message;  
174  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
add headers and body to the Message by invoking the addData method one or  
more times;  
submit the message by invoking the Connection's submit method, passing the  
Messageto it.  
Other methods are available to set various delivery options, select automatic data  
encoding, etc. See the language-specific sections below for more information.  
7.1.1 Requirements  
The submission APIs can be run remotely or locally, as they use a modified version of  
SMTP.  
Applications using the submission APIs must also have the proper authorization. On  
Windows NT/2000, programs must run under either the SYSTEM account or under an  
account belonging to the Administratorsgroup.  
On Unix, programs must either run as root or from an username who belongs to the  
pmtagroup. The pmtagroup is created automatically during PowerMTA's installation.  
The following are required when using the PERL, .NET, or Java APIs:  
PERL 5.12 or newer when using the PERL API  
.NET 2.0 or better when using the .NET API  
Java 1.4.2 or better (for JavaMail: JavaMail and Java Activation Framework from  
Sun's download site as detailed in the JavaDoc from the archive) when using the  
Java API  
PowerMTA needs to be configured with “always-allow-relaying yes” and “allow-  
mailmerge yes” for the appropriate <source>. “always-allow-api-submission yes”  
can be used as well, as this will set “allow-mailmerge yes”. If you want to use  
authentication you need to define users and passwords and allow auth for the  
source.  
It is recommend to add no more than 5000 recipients per batch submission. In the  
event that the batch fails, this will affect fewer recipients. Also, these helps keeps  
memory usage to a minimum.  
7.1.2 Perl Submission API  
In  
Perl,  
three  
objects  
described  
in  
Section  
7.1  
are  
available  
as  
Port25::Submitter::Connection,  
Port25::Submitter::Message  
and  
Port25::Submitter::Recipient.  
175  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
All the methods in the submission API throw an exception in case of an error. Any errors  
render the object unusable, after which you should discard it.  
Here is a brief example on how to submit a message using the Perl submission API:  
use Port25::Submitter::Connection;  
use Port25::Submitter::Message;  
use Port25::Submitter::Recipient;  
eval {  
my $rcpt = new Port25::Submitter::Recipient 'recipient@port25.com';  
$rcpt->setNotify(NOTIFY_FAILURE | NOTIFY_DELAY | NOTIFY_SUCCESS);  
my $msg = new Port25::Submitter::Message 'originator@port25.com';  
$msg->addRecipient($rcpt);  
$msg->setReturnType(RETURN_FULL);  
$msg->setEncoding(ENCODING_8BIT);  
$msg->addDateHeader();  
$msg->addData( "From: originator@port25.com\n"  
. "To: recipient@port25.com\n"  
. "Subject: Test Message via PowerMTA's Perl API\n"  
. "\n"  
. "Hello!\n"  
. "Test message sent via PowerMTA's Perl submission API.\n"  
. "Please ignore this message and have a nice day!"  
);  
my $conn = new Port25::Submitter::Connection('127.0.0.1', 25);  
$conn->submit($msg);  
};  
die "Error: $@\n" if $@;  
exit 0;  
7.1.2.1 ConnectionReference  
new  
Creates a new connection.  
$conn = new Port25::Submitter::Connection($server, $port, $username, $password);  
Arguments:  
$server  
string containing the server to which to connect. Can be given as a numeric  
IP address or a host name.  
$port  
Optional server port on which to connect.(optional, default 25)  
$username  
Optional username for authentication. (optional)  
$password  
Optional password for authentication. (optional)  
176  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Return Value:  
New connection.  
Description:  
Creates a new connection object. If user name and password are given, tries to authenticate at the  
server. If the username or the password is missing, no authentication is sent.  
An Exception is thrown if the object could not be created.  
submit  
Submits a message for delivery.  
$conn->submit($msg);  
Arguments:  
$msg  
message to submit.  
Description:  
Submits a message for delivery.  
An exception is thrown in case of error.  
7.1.2.2 MessageReference  
new  
Creates a new message.  
$msg = new Port25::Submitter::Message($originator);  
Arguments:  
$originator  
Address for the new message's originator.  
Return Value:  
New message.  
177  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Description:  
Creates a new message object.  
An Exception is thrown if the object could not be created.  
setVerp  
Sets whether this is a VERP message.  
$msg->setVerp($isVerp);  
Arguments:  
$isVerp  
TRUEif the message should be VERP.  
Description:  
Sets whether this is a VERP message. If you enable VERP, PowerMTA will encode  
both the originator and recipient addresses in the originator address used for delivering  
the message. This may make tracking any bounces easier, since you can always derive  
the original addresses from the address where the bounce is sent.  
An exception is thrown in case of error.  
setReturnType  
Sets the type of message return requested in delivery reports.  
$msg->setReturnType($type);  
Arguments:  
$type  
This should be one of:  
RETURN_HEADERS (default) return only this message's headers  
RETURN_FULL  
return the full message headers and body  
Description:  
Sets the type of message return requested in delivery reports.  
An exception is thrown in case of error.  
178  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
setEnvelopeId  
Sets this message's envelope ID.  
$msg->setEnvelopeId($envelopeId);  
Arguments:  
$envelopeId  
Envelope ID for this message.  
Description:  
Sets this message's envelope ID.  
An exception is thrown in case of error.  
setVirtualMta  
Selects the VirtualMTA to send this message from.  
$msg->setVirtualMta($virtualMta);  
Arguments:  
$virtualMta  
Name of the VirtualMTA to use (as configured, see Section 8.2).  
Description:  
Selects the VirtualMTA to send this message from.  
An exception is thrown in case of error.  
setJobId  
Sets the job id for this message.  
$msg->setJobId($jobId);  
Arguments:  
$jobId  
id of the job, printable, non-white space characters only.  
Description:  
Sets the job id for this message. This tags the message as belonging to the specified  
179  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
job.  
An exception is thrown in case of error.  
addRecipient  
Adds a recipient to this message.  
$msg->addRecipient($rcpt);  
Arguments:  
$rcpt  
Recipient to add.  
Description:  
Adds a recipient to this message. Do not make any changes to a recipient after it has  
been added to the message or use it a second time. Once added, a recipient should be  
destroyed.  
An exception is thrown in case of error.  
setEncoding  
Sets the kind of encoding to perform on data.  
$msg->setEncoding($encoding);  
Arguments:  
$encoding  
Data encoding desired. This should be either ENCODING_7BIT, ENCODING_8BIT  
or ENCODING_BASE64.  
Description:  
Sets the kind of encoding to perform on data. The encoding applies to all thereafter  
added data. The actual processing performed depends on the encoding selected:  
ENCODING_7BIT and ENCODING_8BIT both select the identity encoding, i.e., no  
transformation is performed on the data, except that any lines terminated with LF alone  
are converted to CRLF. In the case of 7-bit encoding, it is your responsibility to ensure  
that all bytes have their high bit off. ENCODING_BASE64 specifies that any data added  
shall be encoded on the fly using base-64 encoding. No transformation is performed on  
the data prior to encoding, making it possible to transmit binary content. Note,  
however, that to effectively transmit binary data, you must also provide the appropriate  
180  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
MIME headers. In fact, the selected encoding should, in general, agree with the  
Content-Transfer-Encoding header you specify. The default (if this function is  
never invoked) is ENCODING_7BIT.  
An exception is thrown in case of error.  
addData  
Adds (appends) data to this message.  
$msg->addData($data);  
Arguments:  
$data  
Data to add.  
Description:  
Adds (appends) data to this message. Use this function to give this message both its  
headers and a body. How the data you add is handled depends on the kind of encoding  
selected (see setEncoding).  
An exception is thrown in case of error.  
addMergeData  
Adds (appends) merge data to this message.  
$msg->addMergeData($data);  
Arguments:  
$data  
Data to add.  
Description:  
Adds (appends) merge data to this message. Use this function to give this message  
both its headers and a body. How the data you add is handled depends on the kind of  
encoding selected (see setEncoding). Currently only 7-bit and 8-bit encodings are  
supported. If any mailmerge variables are included in the data, they will be substituted  
by their respective values.  
An exception is thrown in case of error.  
181  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
beginPart  
Starts the next mailmerge part which will have the given number.  
$msg->beginPart($num);  
Arguments:  
$num  
positive integer for the part number. No part number may be specified more  
than once.  
Description:  
Starts the next mailmerge part which will have the given number. Note that part 1 is  
started automatically, so the first settable number is 2.  
An exception is thrown in case of error.  
addDateHeader  
Adds (appends) a Date:header to this message.  
$msg->addDateHeader();  
Description:  
This function appends a date header line to the message. It is provided as a  
convenience function only.  
An exception is thrown in case of error.  
7.1.2.3 RecipientReference  
new  
Creates a new recipient.  
$rcpt = new Port25::Submitter::Recipient($address , $options);  
Arguments:  
$address  
The email address for the recipient.  
$options  
182  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
The (optional) options to use while creating the recipient:  
OPTION_NONE  
no special option is used (the default)  
OPTION_NO_ADDRESS_SYNTAX_CHECK  
Disables the check for validity of the recipient's address on submission  
(i.e. prior to sending).  
Return Value:  
New recipient.  
Description:  
Creates a new recipient.  
An exception is thrown if the object could not be created.  
setNotify  
Sets the kind of notification (report) desired for this recipient.  
$rcpt->setNotify($notifyWhen);  
Arguments:  
$notifyWhen  
This should be either NOTIFY_NEVERto indicate that no notification is desired,  
or one or more of the following flags (joined by a bitwise OR):  
NOTIFY_SUCCESS notify in case the delivery is successful  
NOTIFY_FAILURE notify in case of a delivery failure  
NOTIFY_DELAY  
notify in case of a delay in the delivery  
Description:  
Sets the kind of notification (report) desired for this recipient. By default, notification  
is only requested upon delivery failure. Note that while PowerMTA does not support  
notification for delivery delays, the corresponding DSN flag is passed on to the  
receiving mailer, which may support it.  
An exception is thrown in case of error.  
183  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
7.1.3 Java Submission API  
Documentation for the Java APIs is provided in JavaDoc format.  
On Windows NT/2000, it can be found in the pmtajavadoc.zip file in the api\java  
subdirectory of where PowerMTA was installed.  
On Linux, it can be found in the /opt/pmta/api/java/doc/javadoc directory as  
/opt/pmta/api/java/doc/javadoc/index.html.  
On Solaris, it can be found in the /opt/PT25pmta/api/java/doc/javadoc directory as  
/opt/PT25pmta/api/java/doc/javadoc/index.html.  
Currently only Sun's Java SDK is supported. If you need to run it in a different  
environment, please contact Port25 Support at support@port25.com.  
7.1.4 C++ Submission API  
In C++, the three objects described in Section 7.1 are available in the include files  
submitter/Connection.hxx,  
submitter/Message.hxx  
and  
submitter/Recipient.hxx.  
On Windows NT/2000, you can find these files in the api\include subdirectory of  
where PowerMTA was installed. On Linux, that is /opt/pmta/api/include and on  
Solaris, /opt/PT25pmta/api/include.  
All the methods in the submission API throw an exception in case of an error. Any errors  
render the object unusable, after which you should discard it.  
7.1.4.1 Method Reference  
Connection::Connection  
Creates a new connection.  
Connection(const char* server, int port, const char* name  
= "", const char* password = "")  
Arguments:  
server  
server to which to connect, either as an numeric IP address or  
a host name.  
port  
port number to connect to; use 25 for the default SMTP port.  
name  
user name for authentication with the remote server. Leave name  
184  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
and password empty if you don't want to use authentification.  
password  
password to use for authentication. Authentication is done  
with CRAM-MD5, so no password is ever sent to the remote  
server.  
Description:  
Creates a new connection.  
Connection::submit  
Submits a message for delivery.  
void Connection::submit(const Message& message)  
Arguments:  
message  
message to submit.  
Description:  
Submits a message for delivery.  
Message::Message  
Creates a new message.  
Message::Message(const char* originator)  
Arguments:  
originator  
the new message's originator.  
Description:  
Creates a new message.  
Message::setVerp  
Sets whether this message should use the VERP extension.  
void Message::setVerp(bool isVerp)  
Description:  
185  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Sets whether this message should use the VERP extension.  
Message::setReturnType  
Sets the type of message return requested in delivery reports.  
void Message::setReturnType(PmtaMsgRETURN type)  
Arguments:  
type  
This should be one of:  
PmtaMsgRETURN_HEADERS (default) return only this message's headers  
PmtaMsgRETURN_FULL  
return the full message headers and body  
Description:  
Sets the type of message return requested in delivery reports.  
Message::setEnvelopeId  
Sets this message's envelope ID.  
void Message::setEnvelopeId(const char* envelopeId)  
Arguments:  
envelopeId  
envelope ID for this message.  
Description:  
Sets this message's envelope ID.  
Message::setVirtualMta  
Selects the VirtualMTA to use for this message.  
void Message::setVirtualMta(const char* virtualMta)  
Arguments:  
virtualMta  
name of the VirtualMTA to use.  
186  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Description:  
Selects the VirtualMTA to use for this message.  
Message::setJobId  
Sets the job id for this message.  
void Message::setJobId(const char* jobId)  
Arguments:  
jobId  
id of the job, printable, non-white space characters only.  
Description:  
Sets the job id for this message. This tags the message as belonging to the specified  
job.  
Message::addRecipient  
Adds a recipient to this message.  
void Message::addRecipient(const Recipient& r)  
Arguments:  
recipient  
Recipient to add  
Description:  
Adds a recipient to this message. Do not make any changes to a recipient after it has  
been added to the message.  
Message::setEncoding  
Sets the kind of encoding to perform on data.  
void Message::setEncoding(PmtaMsgENCODING encoding)  
Arguments:  
encoding  
Data encoding desired. This should be either PmtaMsgENCODING_7BIT,  
187  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
PmtaMsgENCODING_8BITor PmtaMsgENCODING_BASE64.  
Description:  
Sets the kind of encoding to perform on data. The encoding applies to all thereafter  
added data. The actual processing performed depends on the encoding selected:  
PmtaMsgENCODING_7BIT and PmtaMsgENCODING_8BIT both select the identity  
encoding, i.e., no transformation is performed on the data, except that any lines  
terminated with LF alone are converted to CRLF. In the case of 7-bit encoding, it is  
your  
responsibility  
to  
ensure  
that  
all  
bytes  
have  
their  
high  
bit  
off.  
PmtaMsgENCODING_BASE64 specifies that any data added shall be encoded on the fly  
using base-64 encoding. No transformation is performed on the data prior to encoding,  
making it possible to transmit binary content. Note, however, that to effectively  
transmit binary data, you must also provide the appropriate MIME headers. In fact, the  
selected encoding should, in general, agree with the Content-Transfer-Encoding  
header you specify. The default (if this method is never invoked) is  
PmtaMsgENCODING_7BIT.  
Message::beginPart  
Starts the next mailmerge part which will have the given number.  
void Message::beginPart(int partNum)  
Arguments:  
partNum  
positive integer for the part number. No part number may be specified more  
than once.  
Description:  
Starts the next mailmerge part which will have the given number. Note that part 1 is  
started automatically, so the first settable number is 2.  
Message::addData  
Appends data to this message.  
void Message::addData(const char* data, int length)  
Arguments:  
data  
data to append.  
length  
188  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
length of the data block.  
Description:  
Appends data to this message. Use this method to give this message both its headers  
and a body. How the data you add is handled depends on the kind of encoding selected  
(see setEncoding). All the data is entered as-is, with no mailmerge variable  
substitution being performed. To add mailmerge data, use addMergeData.  
Message::addMergeData  
Appends merge data to this message.  
void Message::addMergeData(const char* data, int length)  
Arguments:  
data  
data to append.  
length  
length of the data block.  
Description:  
Appends merge data to this message. Use this method to give this message both its  
headers and a body. How the data you add is handled depends on the kind of encoding  
selected (see setEncoding). Currently only 7-bit and 8-bit encodings are supported. If  
any mailmerge variables are included in the data, they will be substituted by their  
respective values.  
Message::addData  
Appends null-terminated data to this message.  
void Message::addData(const char* data)  
Arguments:  
data  
null-terminated data to append.  
Description:  
Appends null-terminated data to this message. This is a convenience method to  
facilitate adding C strings directly.  
189  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Message::addMergeData  
Appends null-terminated merge data to this message.  
void Message::addMergeData(const char* data)  
Arguments:  
data  
null-terminated merge data to append.  
Description:  
Appends null-terminated merge data to this message. This is a convenience method to  
facilitate adding C strings directly.  
Message::addDateHeader  
Adds (appends) a Date:header to this message.  
void Message::addDateHeader()  
Description:  
Adds (appends) a Date: header to this message. This method appends a date header  
line to the message. It is provided as a convenience function only.  
Recipient::Recipient  
Creates a new recipient with the given email address.  
Recipient::Recipient(const char* address)  
Arguments:  
address  
e-mail address for the recipient.  
Description:  
Creates a new recipient with the given email address.  
Recipient::setNotify  
Sets the kind of notification (report) desired for this recipient.  
void Recipient::setNotify(int notifyWhen)  
190  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Arguments:  
notifyWhen  
This should be either PmtaRcptNOTIFY_NEVER to indicate that no notification  
is desired, or one or more of the following flags (joined by a bitwise OR):  
PmtaRcptNOTIFY_SUCCESS notify in case the delivery is successful  
PmtaRcptNOTIFY_FAILURE notify in case of a delivery failure  
PmtaRcptNOTIFY_DELAY  
notify in case of a delay in the delivery  
Description:  
Sets the kind of notification (report) desired for this recipient. By default, notification  
is only requested upon delivery failure. Note that while PowerMTA does not support  
notification for delivery delays, the corresponding DSN flag is passed on to the  
receiving mailer, which may support it.  
Recipient::defineVariable  
Defines a new mailmerge variable for this recipient.  
void Recipient::defineVariable(char* name, char* value)  
Arguments:  
name  
the variable's name.  
value  
the variable's value.  
Description:  
Defines a new mailmerge variable for this recipient. PowerMTA will substitute the  
variable for its value during delivery of a mailmerge message.  
7.1.5 C Submission API  
In C, the three objects described in Section 7.1 are available as sets of functions which  
share a common prefix. Connection's functions all begin with PmtaConnand are defined  
in the file submitter/PmtaConn.h; Message's functions all begin with PmtaMsg and are  
defined in the file submitter/PmtaMsg.h; and Recipient's functions all begin with  
PmtaRcptand are defined in the file submitter/PmtaRcpt.h.  
191  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
On Windows NT/2000, you can find these files in the api\include subdirectory of  
where PowerMTA was installed. On Linux, that is /opt/pmta/api/include and on  
Solaris, /opt/PT25pmta/api/include.  
In order to differentiate between "out of memory" conditions and other errors, object  
creation is split in two calls: allocation and initialization. To create an object, you fist call  
its ...Allocfunction. If memory cannot be allocated, a null pointer is returned; otherwise,  
a pointer to the object is returned, which you then pass to the object's initialization  
function: PmtaConnConnect, PmtaMsgInit and PmtaRcptInit, for a Connection,  
Messageor Recipientobject, respectively.  
When done with an object, you should call the object's ...Free method to discard its  
resources.  
Most of the functions in the submission API return a BOOL (boolean) value. You should  
check every return value to make sure that no errors occurred. If an error occurs, you can  
find  
out  
what  
went  
wrong  
by  
calling  
either PmtaConnGetLastError,  
PmtaMsgGetLastErroror PmtaRcptGetLastError(depending on which object the error  
occurred). Any errors render the object unusable, after which you should discard it with  
the appropriate ...Freefunction.  
7.1.5.1 Function Reference  
PmtaConnAlloc  
Allocates a new connection.  
PmtaConn PmtaConnAlloc()  
Return  
Value:  
new connection, or 0 if not enough memory was available.  
Description:  
Allocates a new connection. After allocating, invoke PmtaConnConnect to establish  
the connection to the PowerMTA server.  
192  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
PmtaConnConnect  
Warning: This function is deprecated and may be removed in future  
versions of the API. Use one of the Connect functions below instead.  
Connects to a PowerMTA server.  
BOOL PmtaConnConnect(PmtaConn connection, const char* server)  
Arguments:  
connection  
connection to establish.  
server  
string containing the server to which to connect. Currently this must be  
"local:".  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaConnGetLastError.  
Description:  
Connects to a PowerMTA server.  
193  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
PmtaConnConnectRemote  
Submits a message for delivery.  
PMTACALL(BOOL) PmtaConnConnectRemote(PmtaConn connection, const  
char* server, int port);  
Arguments:  
connection  
connection to establish.  
server  
string containing the server to which to connect. This can be  
a host name or an IP address. Use "127.0.0.1" for the local  
machine.  
port  
to which port to connect. Use 25 for the default SMTP port.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaConnGetLastError.  
Description:  
Connects to a PowerMTA server. No login / authentication is done.  
194  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
PmtaConnConnectRemoteAuth  
Submits a message for delivery.  
PMTACALL(BOOL) PmtaConnConnectRemoteAuth(PmtaConn connection,  
const char* server, int port,  
const char* username,  
const char* password);  
Arguments:  
connection  
connection to establish.  
server  
string containing the server to which to connect. This can be a  
host name or an IP address.  
port  
to which port to connect. Use 25 for the default SMTP port.  
username  
local user name for logging in to PowerMTA. PowerMTA must be  
configured to allow authentication.  
password  
password for the given user name.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be obtained  
with PmtaConnGetLastError.  
Description:  
Connects to a PowerMTA server using the given credentials.  
PmtaConnSubmit  
Submits a message for delivery.  
BOOL PmtaConnSubmit(PmtaConn connection, PmtaMsg message)  
Arguments:  
connection  
connection through which to submit the message.  
message  
message to submit.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaConnGetLastError.  
195  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Description:  
Submits a message for delivery.  
PmtaConnFree  
Discards this connection object, freeing any resouces used by it.  
void PmtaConnFree(PmtaConn connection)  
Arguments:  
connection  
connection to discard.  
Description:  
Discards this connection object, freeing any resouces used by it. This automatically  
closes the connection to the server, if any.  
PmtaConnGetLastError  
Returns the last error occurred on this connection.  
const char* PmtaConnGetLastError(PmtaConn connection)  
Arguments:  
connection  
connection to query for an error.  
Return Value:  
string containing the reason for failure.  
Description:  
Returns the last error occurred on this connection. This function should only be called  
immediately after an error occurred.  
PmtaConnGetLastErrorType  
Returns the type of the last error occurred.  
int PmtaConnGetLastErrorType(PmtaConn connection)  
Arguments:  
196  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
connection  
connection to query for an error.  
Return Value:  
type of the last error occurred, which should normally be one of the PmtaApiERROR  
codes defined in PmtaApi.h.  
Description:  
Returns the type of the last error occurred. This function should only be called  
immediately after an error occurred.  
PmtaMsgAlloc  
Allocates a new message.  
PmtaMsg PmtaMsgAlloc()  
Return Value:  
New message, or 0 if not enough memory was available.  
Description:  
Allocates a new message. Once allocated, the new message must be initialized with  
PmtaMsgInit. Once done with the message, invoke PmtaMsgFreeto free its resources.  
PmtaMsgInit  
Initializes a new message.  
BOOL PmtaMsgInit(PmtaMsg message, const char* originator)  
Arguments:  
message  
Newly allocated message to initialize.  
originator  
Address for the new message's originator.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Initializes a new message.  
197  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
PmtaMsgFree  
Frees memory allocated for this message.  
void PmtaMsgFree(PmtaMsg message)  
Arguments:  
message  
Message to free.  
Description:  
Frees memory allocated for this message.  
PmtaMsgSetVerp  
Sets whether this is a VERP message.  
BOOL PmtaMsgSetVerp(PmtaMsg message, BOOL isVerp)  
Arguments:  
message  
Message to set.  
isVerp  
TRUEif the message should be VERP.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Sets whether this is a VERP message. If you enable VERP, PowerMTA will encode  
both the originator and recipient addresses in the originator address used for delivering  
the message. This may make tracking any bounces easier, since you can always derive  
the original addresses from the address where the bounce is sent.  
PmtaMsgSetReturnType  
Sets the type of message return requested in delivery reports.  
BOOL PmtaMsgSetReturnType(PmtaMsg message, PmtaMsgRETURN type)  
Arguments:  
198  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
message  
Message to set.  
type  
This should be one of:  
PmtaMsgRETURN_HEADERS (default) return only this message's headers  
PmtaMsgRETURN_FULL  
return the full message headers and body  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Sets the type of message return requested in delivery reports.  
PmtaMsgSetEnvelopeId  
Sets this message's envelope ID.  
BOOL PmtaMsgSetEnvelopeId(PmtaMsg message, const char* envelopeId)  
Arguments:  
message  
Message to set.  
envelopeId  
Envelope ID for this message.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Sets this message's envelope ID.  
PmtaMsgSetVirtualMta  
Selects the VirtualMTA to use for this message.  
BOOL PmtaMsgSetVirtualMta(PmtaMsg message, const char* virtualMta)  
Arguments:  
message  
199  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Message to set.  
virtualMta  
name of the VirtualMTA to use.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Selects the VirtualMTA to use for this message.  
PmtaMsgSetJobId  
Sets the job id for this message.  
BOOL PmtaMsgSetJobId(PmtaMsg message, const char* jobId)  
Arguments:  
message  
Message to set.  
jobId  
id of the job, printable, non-white space characters only.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Sets the job id for this message. This tags the message as belonging to the specified  
job.  
PmtaMsgAddRecipient  
Adds a recipient to this message.  
BOOL PmtaMsgAddRecipient(PmtaMsg message, PmtaRcpt recipient)  
Arguments:  
message  
Message to set.  
recipient  
Recipient to add.  
200  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Adds a recipient to this message. Do not make any changes to a recipient after it has  
been added to the message. Once added, a recipient should be freed with  
PmtaRcptFree.  
PmtaMsgSetEncoding  
Sets the kind of encoding to perform on data.  
BOOL PmtaMsgSetEncoding(PmtaMsg message, PmtaMsgENCODING encoding)  
Arguments:  
message  
Message to set.  
encoding  
Data encoding desired. This should be either PmtaMsgENCODING_7BIT,  
PmtaMsgENCODING_8BITor PmtaMsgENCODING_BASE64.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Sets the kind of encoding to perform on data. The encoding applies to all thereafter  
added data. The actual processing performed depends on the encoding selected:  
PmtaMsgENCODING_7BIT and PmtaMsgENCODING_8BIT both select the identity  
encoding, i.e., no transformation is performed on the data, except that any lines  
terminated with LF alone are converted to CRLF. In the case of 7-bit encoding, it is  
your  
responsibility  
to  
ensure  
that  
all  
bytes  
have  
their  
high  
bit  
off.  
PmtaMsgENCODING_BASE64 specifies that any data added shall be encoded on the fly  
using base-64 encoding. No transformation is performed on the data prior to encoding,  
making it possible to transmit binary content. Note, however, that to effectively  
transmit binary data, you must also provide the appropriate MIME headers. In fact, the  
selected encoding should, in general, agree with the Content-Transfer-Encoding  
header you specify. The default (if this function is never invoked) is  
PmtaMsgENCODING_7BIT.  
201  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
PmtaMsgBeginPart  
Starts the next mailmerge part which will have the given number.  
BOOL PmtaMsgBeginPart(PmtaMsg message, int partNum)  
Arguments:  
message  
Message to set.  
partNum  
positive integer for the part number. No part number may be specified more  
than once.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Starts the next mailmerge part which will have the given number. Note that part 1 is  
started automatically, so the first settable number is 2.  
PmtaMsgAddData  
Adds (appends) data to this message.  
BOOL PmtaMsgAddData(PmtaMsg message, const char* data, int length)  
Arguments:  
message  
Message to which to add.  
data  
Data to add.  
length  
Length of the data block.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Adds (appends) data to this message. Use this function to give this message both its  
headers and a body. How the data you add is handled depends on the kind of encoding  
selected (see PmtaMsgSetEncoding). All the data is entered as-is, with no mailmerge  
202  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
variable  
substitution  
being  
performed.  
To  
add  
mailmerge  
data,  
use  
PmtaMsgAddMergeData.  
PmtaMsgAddMergeData  
Adds (appends) mailmerge data to this message.  
BOOL PmtaMsgAddMergeData(PmtaMsg message, const char* data, int length)  
Arguments:  
message  
Message to which to add.  
data  
Mailmerge data to add.  
length  
Length of the data block.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be obtained  
with PmtaMsgGetLastError.  
Description:  
Adds (appends) mailmerge data to this message. Use this function to give this message  
both its headers and a body. How the data you add is handled depends on the kind of  
encoding selected (see PmtaMsgSetEncoding). Currently only 7-bit and 8-bit encodings  
are supported. If any mailmerge variables are included in the data, they will be substituted  
by their respective values.  
PmtaMsgAddString  
Adds (appends) a string to this message.  
BOOL PmtaMsgAddString(PmtaMsg message, const char* str)  
Arguments:  
message  
Message to which to add.  
str  
Null-terminated string to add.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
203  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
obtained with PmtaMsgGetLastError.  
Description:  
Adds (appends) a string to this message. This function is identical to PmtaMsgAddData,  
except that it expects a '0'-terminated string and computes the length of the data  
automatically. It is provided as a convenience function only.  
PmtaMsgAddMergeString  
Adds (appends) a mailmerge string to this message.  
BOOL PmtaMsgAddMergeString(PmtaMsg message, const char* str)  
Arguments:  
message  
Message to which to add.  
str  
Null-terminated string to add.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
Description:  
Adds (appends) a mailmerge string to this message. This function is identical to  
PmtaMsgAddMergeData, except that it expects a '0'-terminated string and computes the  
length of the data automatically. It is provided as a convenience function only.  
PmtaMsgAddDateHeader  
Adds (appends) a Date:header to this message.  
BOOL PmtaMsgAddDateHeader(PmtaMsg message)  
Arguments:  
message  
Message to which to add.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaMsgGetLastError.  
204  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Description:  
Adds (appends) a Date: header to this message. This function appends a date header  
line to the message. It is provided as a convenience function only.  
PmtaMsgGetLastError  
Returns the last error occurred on this message.  
const char* PmtaMsgGetLastError(PmtaMsg message)  
Arguments:  
message  
Message to query for an error.  
Return Value:  
String containing the reason for failure.  
Description:  
Returns the last error occurred on this message. This function should only be called  
immediately after an error occurred.  
PmtaMsgGetLastErrorType  
Returns the type of the last error occurred.  
int PmtaMsgGetLastErrorType(PmtaMsg message)  
Arguments:  
message  
Message to query for an error.  
Return Value:  
Type of the last error occurred, which should normally be one of the PmtaApiERROR  
codes defined in PmtaApi.h.  
Description:  
Returns the type of the last error occurred. This function should only be called  
immediately after an error occurred.  
PmtaRcptAlloc  
205  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Allocates a new recipient.  
PmtaRcpt PmtaRcptAlloc()  
Return Value:  
New recipient, or 0 if not enough memory was available.  
Description:  
Allocates a new recipient. Once allocated, the new recipient must be initialized with  
PmtaRcptInit. When no longer needed (e.g., after adding the recipient to a message),  
its resources should be freed by calling PmtaRcptFree.  
PmtaRcptInit  
Initializes a new recipient.  
BOOL PmtaRcptInit(PmtaRcpt recipient, const char* address)  
Arguments:  
recipient  
Newly allocated recipient to initialize.  
address  
e-mail address for the recipient.  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaRcptGetLastError.  
Description:  
Initializes a new recipient.  
PmtaRcptFree  
Frees storage allocated by this recipient.  
void PmtaRcptFree(PmtaRcpt recipient)  
Arguments:  
recipient  
Recipient to free.  
Description:  
Frees storage allocated by this recipient. To avoid memory leaks, this function should  
206  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
be called on every recipient allocated, whether it has been added to a message or not.  
PmtaRcptSetNotify  
Sets the kind of notification (report) desired for this recipient.  
BOOL PmtaRcptSetNotify(PmtaRcpt recipient, int notifyWhen)  
Arguments:  
recipient  
Recipient to set  
notifyWhen  
This should be either PmtaRcptNOTIFY_NEVER to indicate that no notification  
is desired, or one or more of the following flags (joined by a bitwise OR):  
PmtaRcptNOTIFY_SUCCESS notify in case the delivery is successful  
PmtaRcptNOTIFY_FAILURE notify in case of a delivery failure  
PmtaRcptNOTIFY_DELAY  
notify in case of a delay in the delivery  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaRcptGetLastError.  
Description:  
Sets the kind of notification (report) desired for this recipient. By default, notification  
is only requested upon delivery failure. Note that while PowerMTA does not support  
notification for delivery delays, the corresponding DSN flag is passed on to the  
receiving mailer, which may support it.  
PmtaRcptDefineVariable  
Defines a new mailmerge variable for this recipient.  
BOOL PmtaRcptDefineVariable(PmtaRcpt recipient, const char* name, const char* value)  
Arguments:  
recipient  
recipient whose variable is being defined.  
name  
the variable's name.  
value  
the variable's value.  
207  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Return Value:  
TRUEin case of success, FALSEin case of failure. The cause of the error can be  
obtained with PmtaRcptGetLastError.  
Description:  
Defines a new mailmerge variable for this recipient. PowerMTA will substitute the  
variable for its value during delivery of a mailmerge message.  
PmtaRcptGetLastError  
Returns the last error occurred on this recipient.  
const char* PmtaRcptGetLastError(PmtaRcpt recipient)  
Arguments:  
recipient  
Recipient to query for an error.  
Return Value:  
String containing the reason for failure.  
Description:  
Returns the last error occurred on this recipient. This function should only be called  
immediately after an error occurred.  
PmtaRcptGetLastErrorType  
Returns the type of the last error occurred.  
int PmtaRcptGetLastErrorType(PmtaRcpt recipient)  
Arguments:  
recipient  
Recipient to query for an error.  
Return Value:  
Type of the last error occurred, which should normally be one of the PmtaApiERROR  
codes defined in PmtaApi.h.  
Description:  
Returns the type of the last error occurred. This function should only be called  
208  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
immediately after an error occurred.  
7.1.6 .NET Submission API  
Documentation for the .NET APIs is provided in doc folder.  
On Windows NT/2000, it can be found in the api\dotnet subdirectory of where  
PowerMTA was installed.  
On Linux, it can be found in the /opt/pmta/api/.NETdirectory  
On Solaris, it can be found in the /opt/PT25pmta/api/.NETdirectory  
7.2 Migrating from the Old Submission APIs  
In PowerMTA v3.5 we redesigned our submission APIs, incorporating customer  
requests, facilitating planned enhancements, as well as tidying up the design a little to  
make it more intuitive and easier to use. While the differences between old and new APIs  
are not huge, this section is intended to facilitate the migration to the new APIs.  
7.2.1 Overview of Differences Between Old and  
New APIs  
The most notable difference is, that all APIs now support remote feeding. To use the new  
APIs, you will need to recompile your existing APIs using the new libraries. In addition  
to the remote feeing, PowerMTA now uses a modified version of SMTP. This modified  
version is our MAIL MERGE feature set and can help with increasing the feeding rate  
into PowerMTA. For more information on MAIL MERGE, see Section 9.  
7.3 Accounting APIs  
Currently the binary accounting file is still supported, but the accounting APIs for reading  
the older binary accounting file have been deprecated. The CSV accounting files, being  
plain text, do not require an API.  
7.4 Pickup Directory  
PowerMTA can be instructed to pick up message files from a directory. To submit a  
message, you write it to a file, formatting it according to Internet e-mail standards but  
preceding it with envelope information in special headers: x-sender, x-receiver and,  
optionally, x-envid and x-job. You then move this file to the pickup directory, from  
209  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
         
where PowerMTA reads it into its message spool and performs delivery.  
recommend to add no more than 5000 recipients per pickup file.  
It is  
The x-sender header should be in the first line in the file, followed by one or more x-  
receiverheaders, each in its own line. You can also optionally set the DSN envelope ID  
and the job ID by adding the x-envid and x-job headers respectively. The x-sender  
and x-receiverheaders must contain the e-mail addresses only, with no free form name,  
no "<>"s, etc., like in:  
x-sender: me@over.here  
x-receiver: you@over.there  
x-receiver: someone.else@some.other.place  
x-envid: me-0001  
x-job: love-2003-01  
From: Myself Personally <me@over.here>  
To: You <you@over.there>  
Date: Thu, 6 Jul 2000 07:45:43 -0400  
Subject: I love it  
Hey, did you know that ...  
Note that in the example above, someone.else@some.other.place is BCC'ed, i.e.,  
blind copied: he or she receives a copy of the message but is not included in the recipient  
headers.  
PowerMTA's pickup directory also supports the x-sender-override header, which  
allows you to override the contents of x-sender. If x-sender-override is present, its  
contents override the sender specified in x-sender, if any. This is useful when you wish  
to customize the message sender despite the software you're using to create the messages  
not allowing for that. Typically that software will still allow you to pass additional  
headers, such as x-sender-override.  
Other than reading the sender and receiver e-mail address headers and removing them  
from the message, no other header or body processing takes place. You are responsible  
for properly formatting the message.  
Instead of creating the file elsewhere and then moving to the pickup directory, it is also  
possible to create the file directly in it. However, since PowerMTA must repeatedly  
attempt to lock the file for exclusive access, it is less efficient to do so.  
To configure PowerMTA for a pickup directory, specify the pickup directory as  
described in Section 3.2.13. You must also specify a directory as the "bad mail"  
directory, to which messages are moved if there is a permanent error processing the  
message.  
210  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
7.4.1 BSMTP files  
Starting with PowerMTA v3.0, the pickup directory now also supports BSMTP (batched  
SMTP) files. A BSMTP file is simply a file that contains all of the SMTP commands  
necessary for submitting a message batched together in one text file, as in the example  
below:  
MAIL FROM:<me@over.here>  
RCPT TO:<you@over.there>  
DATA  
From: Myself Personally <me@over.here>  
To: You <you@over.there>  
Date: Thu, 6 Jul 2000 07:45:43 -0400  
Subject: I love it  
Hey, did you know that ...  
.
The pickup directory supports the following SMTP commands: HELO, EHLO, MAIL, RCPT  
and DATA. Additionally, it also supports PowerMTA's extended SMTP mailmerge  
commands (XMRG, XDFN, XPRT and XACK), allowing for both mailmerge and non-  
mailmerge messages to be created.  
To be recognized as such, BSMTP files need not be marked in any special way, other  
than the first command be one of: HELO, EHLO, MAIL, XACKor XACK.  
Like in traditional pickup files, only one message may be submitted per file. However,  
since mailmerge is supported, the message submitted may actually be a template used for  
many recipients. See Section 9.5.3 for examples on using the pickup directory for  
submitting mailmerge messages.  
211  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
If any commands cannot be successfully processed, the entire file is rejected and moved  
to the "bad file" directory. For certain recipient address related errors, however, you have  
the option of requesting that PowerMTA bounce the recipient rather than rejecting the  
file during submission. This is activated by disabling recipient acknowledgements, using  
PowerMTA's XACKSMTP extension, like in the example below:  
XACK OFF  
MAIL FROM:<me@over.here>  
RCPT TO:<you@over.there>  
RCPT TO:<notyou@not..here>  
DATA  
From: Myself Personally <me@over.here>  
To: (recipients omitted)  
Date: Thu, 6 Jul 2000 07:45:43 -0400  
Subject: I love it  
Hey, did you know that ...  
.
In the example above, despite the error in the second recipient's domain, the file would  
not be rejected, but a bounce would be sent to the address in the MAIL FROM.  
Section 9.5.2 describes PowerMTA's mailmerge extensions; look at Section 9.5.4 for the  
XACKextension.  
7.5 Pipe Delivery  
PowerMTA can be configured to deliver e-mail to another program on the same machine.  
It does so by starting the program for each new recipient and writing the message to the  
program's standard input. The mechanism used to pass on the message is called "pipe", so  
this feature is named "pipe delivery".  
****Important note****  
Any pipe program should work outside of PowerMTA by simply feeding data into it via  
an echo command or orther such standard out (e.g. cat-ing a file). If a program does not  
work outside of PowerMTA, it will not work inside of PowerMTA. If the program works  
outside of PowerMTA, but not inside PowerMTA then the issue is mostly a permissions  
issue in the directory/file to which PowerMTA is trying to write.  
To use pipe delivery, you add domain definitions for one or more domains, specifying a  
typeof pipeand defining the command to run for starting the pipe receiver program. For  
example:  
<domain bounces.company.com>  
type pipe  
command "c:\\path\\bounceproc.exe --envid $envid"  
</domain>  
212  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Note that since the backslash character is also used for escaping other characters (such as  
spaces, quotes and the dollar sign), you need to specify it twice where you want just one  
to appear. On Windows NT/2000, you can also use the (forward) slash character to  
specify paths, so in the example above it could have been c:/path/bounceproc.exe.  
Before starting the program, PowerMTA substitutes any macros found in the command  
line (such as $envidin the example above), allowing you to pass on additional message-  
related parameters to the pipe receiver program. The complete list of macros supported  
and other configuration directives for pipe domains are described in Section 3.2.12.  
7.5.1 Delivering mail to local users  
PowerMTA's pipe delivery can be used to deliver e-mail to local users. The special local  
domain name makes this simple to configure by concentrating all e-mail destined to  
recipients on any of the local domains. PowerMTA will use the hostname of the OS, or  
and host-names configured in PowerMTA, to determine if an email is local. On Unix  
systems, it is often sufficient to specify procmail as the command to execute for pipe  
delivery:  
<domain local>  
type pipe  
command "/usr/bin/procmail -t -Y -d $user"  
</domain>  
Note, however, that PowerMTA does not currently process the /etc/aliases or  
.forwardfiles.  
Alternatively, the same could be done be explicitly specifying the domain name as in this  
example:  
<domain bounces.yourdomain.com>  
type pipe  
command "/usr/bin/procmail -t -Y -d $user"  
</domain>  
The same is also available on Windows NT/2000, but you will need to provide a pipe  
delivery processor that can write the messages in a way your user agents (i.e., e-mail  
clients) understand.  
7.5.2 Pipe Delivery Programs Included With  
PowerMTA  
PowerMTA comes with two (fully functional) sample programs to be used with the new  
pipe delivery functionality; appendtofile, which appends messages to a file, and  
newfile, which writes each message to a separate (new) file.  
213  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
appendtofile appends the message and / or arguments passed to it to the file  
specified. The syntax for appendtofileis:  
appendtofile [--nomsg] filename [text]  
where filename is the name of the file to which to append the data and text is an  
optional text or a supported macro to write in front of each message. If the first  
command line argument given to appendtofile is --nomsg (or /nomsg), it will  
just apppend the text or the macro's value to the file. You can thus choose to  
either save the complete message to the file or just the summary data passed on  
the command line, such as only the recipient address of the message (when using  
the $tomacro).  
newfile writes each message to a separate (new) file. The syntax for newfileis  
simply:  
newfile dirname  
where dirname is the directory where the message file should be created. If the  
given directory does not yet exist, newfileautomatically creates it. Each message  
file name is automatically generated by newfile, and will have a '.msg' extension.  
For greatest flexibility, you can use the supported macro substitutions described in  
Section 3.2.12 to automatically pass message-dependent file names and directory names.  
For example, appendtofile c:/pipe/$domain in the command directive will append  
messages to the file named after the domain of the recipient address, given the presence  
of the $domainmacro. A message sent to test@port25.comwould be appended to a file  
named port25.com  
in  
the  
directory c:\pipe,  
while  
a
message  
sent  
to  
test@powermta.com would be appended to a file named powermta.com in the same  
directory.  
In the typical scenario where the pipe delivery applications are used to store and process  
bounces, using the $domain macro results in files named after the originator / SMTP  
MAIL FROM domain you used in your original messages, since the recipient address of a  
bounce report is the original MAIL FROMaddress used.  
For example, if you used a MAIL FROM domain of bounces5.port25.com for all of your  
messages for customer or campaign ID #5, the file bounces5.port25.comwould contain  
the bounce reports for the messages of this customer or campaign. The configuration for  
this would be;  
<domain bounces5.port25.com>  
type pipe  
command "c:/pmta/bin/appendtofile.exe c:/pipe/$domain"  
</domain>  
214  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Alternatively, with the --nomsg and passing the $to macro to appendtofile as well,  
like in  
<domain bounces5.port25.com>  
type pipe  
command "c:/pmta/bin/appendtofile.exe --nomsg c:/pipe/$domain $to"  
</domain>  
only the recipients would be written to a file (given the $to), which is named after the  
domain of the recipients (given the $domain), port25.com.  
With newfile, if you had a configuration like  
<domain bounces5.port25.com>  
type pipe  
command "c:/pmta/bin/newfile.exe c:/pipe/$domain"  
</domain>  
newfile will create subdirectories named after the recipients' domains, and only create  
message files within the appropriate subdirectories. Using the example above with the  
domain bounces5.port25.com as the domain of your originator address, when bounces  
come in, the directory created would be c:\pipe\bounces5.port25.com, and which  
would contain only files / message received for the recipientrs of that domain. If you had  
PowerMTA handling inbound mail for 50 separate domains, newfile would create 50  
separate subdirectories, each named for a different domain, and containing only messages  
for that domain.  
7.5.3 Accessing Files Created By The Sample  
Applications  
Since, in principle, new messages may be delivered at any time through the sample  
applications, to avoid loss of data special care must be taken when accessing the files  
these applications create.  
newfile solves concurrency conflicts by using a naming convention: it initially creates  
files with a .tmp suffix ("extension") and when done writing to them, renames them to  
.msg. This makes it very easy to access the files: you can freely access all the .msgfiles,  
while leaving any .tmpfiles alone.  
Doing the same for appendtofileis a little more challenging, since it writes data to the  
same file and due to the differences in file lock handling across the PowerMTA  
platforms. To allow access to appendtofile-generated files in a simple and uniform  
way, Port25 provides a program named pmtagetfile, which moves the contents of a  
given file.  
215  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
To use pmtagetfile, you simply run it passing the name of the file to which  
appendtofile writes and the new destination file name on the command line. For  
example,  
pmtagetfile c:/pmta-pipe/port25.com.txt c:/tmp/port25.com.txt  
moves the file c:\pmta-pipe\port25.com.txtto c:\tmp\port25.com.txt.  
Once in the new directory, the file is out of appendtofile's reach, and you can safely  
process it as required. Note that the pmtagetfile program will fail if the first file listed  
does not exist (nothing to copy from) or if the second file already exists (preventing  
accidential overwriting of previous data). Also, pmtagetfile does not work across file  
system boundaries, i.e., the the new file must be on the same file system or drive (on  
Unix and Windows NT/2000 systems, respectively). To move a file to a different file  
system, use pmtagetfileto first move it away from appendtofileto a safe place on the  
same file system, and then move that file with your usual tools (Explorer, shell  
commands, etc.) to the desired location.  
Please note that pmtagetfile is only intended for use with files written by  
appendtofileor with files written to by File Delivery.  
7.5.4 Writing Your Own Pipe Delivery Programs  
For convenience and flexibility, the sample pipe delivery programs detailed above are  
also provided in source code, allowing you to modify or customize as needed.  
The program used for pipe delivery should terminate with certain specific exit codes. On  
Unix systems, these are defined in /usr/include/sysexits.h. On Windows NT/2000,  
a corresponding file is included in the api\include directory. Depending on the exit  
code, PowerMTA will consider the delivery to have succeeded or to have temporarily or  
permanently failed and generate any DSN delivery reports as appropriate:  
exit code  
action  
DSN status  
delete  
2.0.0 (success)  
EX_OK  
bounce 5.5.4 (invalid command arguments)  
bounce 5.1.1 (bad destination mailbox address)  
bounce 5.1.2 (bad destination system address)  
bounce 5.2.0 (mailbox-related failure)  
EX_USAGE  
EX_NOUSER  
EX_NOHOST  
EX_CANTCREAT  
EX_UNAVAILABLE  
EX_SOFTWARE  
bounce 5.3.0 (mail system-related failure)  
bounce 5.3.0 (mail system-related failure)  
216  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
bounce 5.3.0 (mail system-related failure)  
bounce 5.3.0 (mail system-related failure)  
EX_OSFILE  
EX_NOINPUT  
EX_OSERR  
retry  
retry  
retry  
4.3.0 (mail system-related failure)  
4.3.0 (mail system-related failure)  
4.0.0 (transient failure)  
EX_IOERR  
EX_TEMPFAIL  
EX_DATAERR  
EX_PROTOCOL  
EX_CONFIG  
EX_NOPERM  
bounce 5.5.2 (syntax error)  
bounce 5.5.0 (protocol-related failure)  
bounce 5.3.5 (system incorrectly configured)  
bounce 5.7.1 (delivery not authorized)  
If you use appendtofilebut for some reason would like to replace pmtagetfile, please  
look into pmtagetfile's sources first to better understand how it works to avoid file  
locking conflicts.  
7.6 Cold Fusion Tag (CFX_PMTA)  
Due to lack of demand and increased technical problems, support for the custom Cold  
Fusion submission API has been officially dropped from PowerMTA v2.0 and future  
versions.  
This section is provided only as a courtesy to assist those that would still like to try and  
run the unsupported CFX_PMTA Tag given their current application and infrastructure.  
Note that this tag only runs on Windows NT/2000, but which again, is no longer  
officially supported by Port25.  
The CFX_PMTAtag allows you to submit e-mail messages to PowerMTA from within Cold  
Fusion applications. It is designed to mimick and extend both the functionality and the  
syntax of Cold Fusion's built-in CFMAILtag.  
If you intend to use the Cold Fusion submission tag, register the new tag library  
(C:\pmta\api\cfx_pmta.dll) as a C++ CFX tag using Cold Fusion's administrative  
pages. We suggest using the name cfx_pmta for the tag. To avoid conflicts next time  
PowerMTA is installed, it is usually a good idea to copy the tag library file to a different  
directory and register it from there. You may need to re-start the Cold Fusion server  
before the changes are accepted.  
7.6.1 Sending E-mail With the CFX_PMTA Tag  
The tag's syntax is:  
217  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
<CFX_PMTA TO="recipient"  
FROM="sender"  
CC="copy_to"  
BCC="blind_copy_to"  
SUBJECT="msg_subject"  
TYPE="msg_type"  
MIMEATTACH="path"  
SERVER="servername"  
PORT="tcp port"  
MAILERID="headerid"  
TIMEOUT="seconds"  
HEADER_...="custom header"  
ENVID="envelope ID"  
BODY="message body"  
HTMLBODY="alternative HTML-formatted message content">  
where SERVER, PORTand TIMEOUTare for compatibility with CFMAILonly and are ignored  
by PowerMTA.  
CFMAIL's QUERY, MAXROWS, GROUP, GROUPCASESENSITIVEand STARTROWare not supported  
and will cause an error if used. The lack of direct support for queries can be easily  
overcome by using CFOUTPUT, however, as in the example below:  
<cfquery name="q" ...> ... </cfquery>  
<cfoutput query="q" ...>  
<cfx_pmta to="#email#" ...>  
</cfoutput>  
Cold Fusion's API does not allow for the processing of content in a custom tag, so the  
message's body must be passed in the BODYattribute, as in the example below:  
<cfx_pmta from="me@over.here"  
to="you@over.there"  
subject="test e-mail"  
body="  
Hello, ColdFused World!  
...  
">  
The same restriction also prevents us from providing a tag that mimicks the CFMAILPARAM  
functionality.  
The ENVID tag allows you to specify the DSN (RFC 1891) Envelope ID, which can be  
used for tracking purposes within PowerMTA since the accounting files include it, and  
DSN-capable mailers will include it in their delivery report messages (e.g., bounces) as  
well.  
218  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
TYPEspecifies the content type for BODY. If it is not specified, the default is a text/plain  
body. Currently, "HTML" is the only supported value. You would use it when sending  
HTML content only, by specifying the contents in BODYand TYPE="HTML".  
HTMLBODY is an extension to the original CFMAIL syntax. You can use it to create  
messages with a multipart/alternative body part between the contents of BODY  
(usually the plain text version) and HTMLBODY (which is always text/html). Since BODY  
contains the plain text version of the message, you don't specify the TYPEattribute, like in  
the example below:  
<cfx_pmta from="me@over.here"  
to="you@over.there"  
subject="test e-mail"  
body="  
Dear you,  
...  
"
htmlbody="  
<html><body>  
Dear you,  
...  
</body></html>  
">  
Tags beginning with HEADER_ can be used to add custom headers to the message. Since  
hyphens ("-") may not be specified in attribute names, any underscores ("_") found in the  
attribute name are mapped to hyphens. To specify an underscore in your custom header,  
simply specify two in a row. For example, using  
<cfx_pmta ... header_X_Custom__Header="text">  
will produce a X-Custom_Header: textheader in the message.  
Note that only e-mail addresses are allowed in the from, to, cc and bcc attributes. You  
can, however, add a free form name to the corresponding message headers by using  
header_...attributes:  
<cfx_pmta from="me@over.here" header_From="Me <me@over.here>"  
to="you@over.there" header_To="You <you@over.there>"  
...  
body="  
...  
">  
219  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
7.6.2 Compiling the CFX_PMTA Tag  
For your convenience and greater flexibility, we ship both a precompiled version of the  
tag and the C++ source code to it. You can create a customized tag by modifying the  
source code and recompiling it (using Visual Studio):  
cl /LD /MT /GX /Ic:\pmta\api\include /Ic:\cfusion\cfx\include /D "_WIN32"  
cfx_pmta.cxx /link c:\pmta\api\lib\pmta.lib ws2_32.lib advapi32.lib  
assuming C: to be the drive on which PowerMTA has been installed. You may need to  
change the ColdFusion include path as well.  
The compilation will yield (among other files) a new cfx_pmta.dll, which you can use  
instead of the one shipped along with PowerMTA.  
220  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
8. VirtualMTA Support  
8.1 Overview  
Increasing volumes of e-mail have prompted many ISPs and e-mail administrators to  
proactively filter or block incoming e-mail. While their intentions are honest, this also  
results in the blocking of legitimate mail for sites running on or delivering through a  
shared mail gateway. Traditionally, all mail sent from a shared MTA or gateway is sent  
from same host name and IP addresses. Since ISPs and e-mail administrators tend to  
initially key on the source IP address for blocking incoming mail, more aggressive  
senders, or simply higher volume customers delivering through a shared MTA will  
almost certainly put all others at risk of being blocked.  
To maximize deliverability and minimize collateral blocking of legitimate email on  
shared gateways, Port25 has developed VirtualMTA technology within PowerMTA.  
Simply put, this functionality allows sites to define and control both the source IP address  
and host name for each message. This allows for creating VirtualMTAs for separate and  
specific campaigns, customers or departments, while still running just one instance of  
PowerMTA.  
8.2 VirtualMTA Definitions  
VirtualMTAs are defined via the new <virtual-mta>directive. Defining a VirtualMTA  
entails creating a <virtual-mta> group with the desired alias and listing its host name  
and SMTP source IP(s). For example, if you wanted to create a VirtualMTA named mta1,  
you would simply add in the configuration file:  
<virtual-mta mta1>  
smtp-source-host 1.2.3.4 mta1.port25.com  
</virtual-mta>  
Changes to the VirtualMTA definitions are reloadable via the pmta reload command  
and thus do not require a restart.  
Note that if you leave out the smtp-source-hostdirective in the definition, PowerMTA  
will use the corresponding global settings for that VirtualMTA. Since that may or may  
not be the desired result, Port25 always recommends that you specify those directives  
within each VirtualMTA definition. For example, you could use the desired host name as  
the VirtualMTA alias, but you would still need to specify the host-name directive to  
ensure that the right host name is used:  
221  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
<virtual-mta mta2.port25.com>  
smtp-source-host 2.3.4.5 mta2.port25.com  
</virtual-mta>  
Lastly, if more than one smtp-source-hostaddress is listed in a definition, PowerMTA  
will use the various source IPs in round robin fashion for connections from that  
VirtualMTA:  
<virtual-mta mta3>  
smtp-source-host 1.2.3.4 mta4.port25.com  
smtp-source-host 2.3.4.5 mta5.port25.com  
smtp-source-host 3.4.5.6 mta6.port25.com  
</virtual-mta>  
VirtualMTA directives only apply when the VirtualMTA has been selected as described  
in Section 8.4. Otherwise, they are simply ignored. Note that the host-name and smtp-  
source-host directives are also global system directives, detailed in Chapter 3.  
8.3 VirtualMTA Pools  
PowerMTA supports the defining and selecting of VirtualMTA pools per message or  
campaign as well, which are basically multiple VirtualMTAs grouped in a pool. When a  
pool is defined and selected for a campaign, PowerMTA will use the VirtualMTAs listed  
in round robin fashion for connections from that pool.  
VirtualMTA pools are defined via the new <virtual-mta-pool> directive. Defining a  
pool entails creating a <virtual-mta-pool> group with the desired alias and listing the  
VirtualMTAs that you want belonging to that pool. For example, if you wanted to create  
a VirtualMTA pool named pond, you would first define the specific VirtualMTAs to be  
part of pond, as described in Section 8.2, and then subsequently list each of the  
VirtualMTAs that is to be included using the virtual-mtadirective:  
<virtual-mta mta1>  
smtp-source-host 1.2.3.4 mta1.port25.com  
</virtual-mta>  
<virtual-mta mta2>  
smtp-source-host 2.3.4.5 mta2.port25.com  
</virtual-mta>  
<virtual-mta-pool pond>  
virtual-mta mta1  
virtual-mta mta2  
</virtual-mta-pool>  
222  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Note that PowerMTA will not accept a VirtualMTA pool definition if the pool name  
equals a previously defined VirtualMTA name, given that you select a VirtualMTA pool  
and/or VirtualMTA via the same headers and function calls, as detailed in Section 8.4.  
8.4 Selecting a VirtualMTA or VirtualMTA Pool  
PowerMTA supports various methods of selecting a VirtualMTA (or pool), depending on  
your submission method:  
Submission APIs:  
o
by defining the *vmtamailmerge variable in mailmerge messages;  
o
by using the setVirtualMta or equivalent method (see Chapter 7 for  
details);  
Pickup directory submission:  
o
by defining the *vmtamailmerge variable in mailmerge messages;  
by pattern matching based on the MAIL FROM, RCPT TO, or a header.  
o
SMTP submission:  
o
by defining the *vmtamailmerge variable in mailmerge messages;  
o
by including a X-virtual-MTA header in the message (see Section 8.4.1  
below for details);  
o
o
by regular expression matching of the SMTP MAIL FROM or RCPT TO  
addresses, or a message header; see Section 3.2.16 and the pattern-list  
directive in Section 3.2.4 as well as Section 8.4.2 below for details);  
by configuring a default VirtualMTA on a <source>directive selected by  
the IP address and port in the PowerMTA machine that you connect to  
(see the smtp-listenerdirective in Section 3.2.4 as well as Section 8.4.3  
below for details);  
o
by configuring a default VirtualMTA on a <source>directive selected by  
the source IP address (see the default-virtual-mtadirective in Section  
3.2.4 as well as Section 8.4.4 below for details);  
The selection methods above are listed in the order of precedence within each submission  
methods.  
Using mailmerge may effect how VirtualMTA selection is done. When using mailmerge  
and the API or SMTP, the x-virtual-mta will apply to the entire mailmerge job, not  
individual recipients (in most cases using the first defined x-virtual-mta).  
When using mailmerge and pattern lists, VirtualMTA selection will be for each recipient  
when matching the RCPT TO, and will only be for each recipient for the MAIL FROM  
when using the *from mailmerge variable. When not using the *from, or when using  
header matching, *all* recipients in the mailmerge job will use the same VirtualMTA (in  
most cases the first matched pattern).  
223  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Note that one selects a VirtualMTA pool using the same exact header, directives or  
function call, but using the pool name instead of the VirtualMTA name.  
8.4.1 Selecting a VirtualMTA with a  
Header  
X-virtual-MTA  
To select a VirtualMTA with the X-virtual-MTAheader, you need to:  
1. define the VirtualMTA(s) or VirtualMTA pool(s) in the configuration file using  
the <virtual-mta>directive;  
2. define the specific IP address or IP address range for the source of the messages  
that it is applicable using the expanded <source>directive;  
3. define the ability for PowerMTA to process the x-virtual-mta header via the  
process-x-virtual-mta directive, within the <source> directive defined in  
step 2;  
After setting up the configuration file properly, you simply need to then add the x-  
virtual-mtaheader to your message specifying the VirtualMTA's alias, like in  
x-virtual-mta: yyyyy  
where yyyyy is the VirtualMTA's alias in the configuration file. Note that PowerMTA  
will parse and remove the header before ultimate delivery, so it will not be seen by the  
recipient's mail gateway or the recipient.  
For example, assuming that you had the following VirtualMTA definition in your  
configuration file:  
<virtual-mta mta1>  
smtp-source-host 1.2.3.4 mta1.port25.com  
</virtual-mta>  
and you wanted PowerMTA to process the x-virtual-mta header from mail only  
coming from the local IP address 127.0.0.1 for selecting a VirtualMTA, you would need  
to have at a minimum the following in your configuration file;  
<source 127.0.0.1>  
process-x-virtual-mta yes # allow selection of a VirtualMTA  
always-allow-relaying yes # allow feeding from 127.0.0.1  
</source>  
With this, any messages submitted from the local IP address 127.0.0.1 that contained the  
header x-virtual-mta: mta1 would have PowerMTA using VirtualMTA mta1 and its  
parameters when making connections to deliver these messages. One can also select a  
VirtualMTA pool to be used for messages in the same manner.  
224  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
The entire message (in this example, submitted through the pickup directory) could thus  
read:  
x-sender: me@over.here  
x-envid: me-0001  
x-receiver: you@over.there  
x-virtual-mta: mta1  
From: Myself Personally <me@over.here>  
To: You <you@over.there>  
Date: Thu, 13 Mar 2003 07:45:43 -0400  
Subject: PowerMTA is the best  
Hey, this new VirtualMTA technology really improves delivery  
rates!  
8.4.2 Selecting a VirtualMTA by Regular  
Expression Matching  
Sites can also have PowerMTA use a VirtualMTA or VirtualMTA pool for specific  
messages by way of regular expression pattern matching of the SMTP MAIL FROM  
address, the SMTP RCPT TOaddress, or a header, based on the IP address of the source of  
the message.  
To select a VirtualMTA or VirtualMTA pool based on regular expression pattern  
matching, you  
1. define the VirtualMTAs or VirtualMTA pools in the configuration file using the  
<virtual-mta>directive;  
2. define the alias for the regular expression pattern list using the <pattern-list>  
directive;  
3. define the actual regular expression pattern to use for matching the SMTP MAIL  
FROM, the RCPT TO address, or a header as well as subsequent VirtualMTA or  
VirtualMTA pool to use when a match occurs, via the mail-from, rcpt-to, and  
header directives. These directives are defined within the <pattern-list>  
definition created in step 2;  
4. define the specific IP address or IP adress range for the source of the messages  
that is applicable within the expanded <source>directive;  
5. define the pattern-listdirective using the corresponding alias defined in step 2  
within the <source> directive defined in step 4. Conditional pattern matching as  
defined in Section 3.2.16 may also be used.  
225  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
For example, assuming that you had the following VirtualMTA definitions in your  
configuration file:  
<virtual-mta mta1>  
smtp-source-host 1.2.3.4 mta1.port25.com  
</virtual-mta>  
<virtual-mta mta2>  
smtp-source-host 2.3.4.5 mta2.port25.com  
</virtual-mta>  
and you wanted PowerMTA to match the patterns "abc" and "xyz" at the beginning of the  
MAIL FROM address in order to select the appropriate VirtualMTA to use for each, you  
would need to have at a minimum the following in your configuration file:  
<pattern-list group2>  
mail-from /^abc/ virtual-mta=mta1  
mail-from /^xyz/ virtual-mta=mta2  
</pattern-list>  
<source 127.0.0.1>  
pattern-list group2  
always-allow-relaying yes  
# this selects the pattern list for messages from this IP  
# allow feeding from 127.0.0.1  
</source>  
With this, any messages submitted from the local IP address 127.0.0.1 would have  
PowerMTA using regular expression matching on the MAIL FROM address, and if  
PowerMTA found "abc" at the beginning of the address (for example abc-  
2890u8@bounces.port25.com), VirtualMTA mta1 and its parameters would be used  
when making connections to deliver these messages. For messages submitted that had a  
MAIL FROM starting with "xyz", for example xyz-ljwer@bounces.port25.com,  
VirtualMTA mta2 and its parameters would instead be used when making connections to  
deliver these messages.  
To additionally select some other VirtualMTA for recipients at yahoo.com, you could  
add a rcpt-todirective as below:  
<pattern-list group2>  
mail-from /^abc/ virtual-mta=mta1  
mail-from /^xyz/ virtual-mta=mta2  
rcpt-to /@yahoo.com$/ virtual-mta=mta3  
</pattern-list>  
...  
Per the simple examples above, you can see that PowerMTA can use different matching  
patterns for different campaigns, customers and/or mailings simultaneously, in order to  
use different VirtualMTAs or VirtualMTA pools for each.  
226  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
More than one mail-from, rcpt-to and header directives are allowed within a  
<pattern-list> definition, and since the first match is used, you will want to list the  
most likely matches first. Only one pattern-listis allowed within a <source>group.  
Conditional matching is allowed as well. For example, if you want wanted all emails that  
have a MAIL FROM of X, and a RCPT TO of Y, that is allowed in a pattern similar to  
the following:  
<pattern-list patterns>  
mail-from /X/ <pattern-list>  
rcpt-to /Y/ virtual-mta=vmta2  
rcpt-to /Z/ virtual-mta=vmta1  
* virtual-mta=vmta2  
</pattern-list>  
</pattern-list>  
For more information on conditional pattern matching, see Section 3.2.16.  
Note that simple to advanced regular expression pattern matching is supported, and  
which is based on Perl Compatible Regular Expressions (PCRE).  
8.4.3 Selecting a VirtualMTA by the IP  
Address/Port Receiving Connections  
For added flexibility, PowerMTA supports the ability to select a VirtualMTA based on  
the IP address (and TCP port number) on the PowerMTA machine to which you connect  
when submitting your messages.  
For example, if you have 10 VirtualMTAs defined, each with a different IP address, you  
could select the VirtualMTA to use for each message simply by making your SMTP  
connection to the specific IP address defined on your PowerMTA machine for the  
specific VirtualMTA.  
This is accomplished through "named" <source> tags, in conjunction with the smtp-  
listener directive. Named <source> tags allow you to specify directives that override  
those normally selected by source IP address; they apply only when referenced in the  
smtp-listenerdirective (and for authenticated users — see Section 10.2.2).  
For example, to select VirtualMTA vmta1 by its assigned smtp-source-host address  
1.2.3.4and the standard SMTP port (25), you would configure:  
<virtual-mta vmta1>  
smtp-source-host 1.2.3.4 vmta1.yourdomain.com  
...  
</virtual-mta>  
227  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
<source vmta1>  
default-virtual-mta vmta1  
</source>  
smtp-listener 1.2.3.4:25 source=vmta1  
Multiple smtp-listener entries can be specified in a configuration file, each of which  
specifying a different IP address and/or port.  
Note that if any smtp-listener directives are specified, all listeners must be explicitly  
defined: PowerMTA no longer starts a listener automatically based on the value of the the  
smtp-ip and smtp-port directives. When configuring your first smtp-listener entry,  
to retain the default listener you should add another smtp-listenerdirective specifying  
your smtp-ip and smtp-port in it. If you have no smtp-ip configured, use 0.0.0.0  
instead, which causes PowerMTA to bind to all local IP addresses:  
smtp-listener 0.0.0.0:25  
Since the named source's directives apply to anyone who can connect to the listener's IP  
address and port, one should be careful about what is entered there. For example,  
always-allow-relaying should most probably not be enabled in the named source.  
Instead, permission for relaying, for accessing the mailmerge extensions, etc. should be  
based on authenticated sources (see Section 10.2.2) or on the source IP address, as in the  
example below:  
<virtual-mta vmta1>  
smtp-source-host 1.2.3.4 vmta1.yourdomain.com  
...  
</virtual-mta>  
smtp-listener 1.2.3.4:25 source=vmta1  
smtp-listener 0.0.0.0:26  
<source vmta1>  
default-virtual-mta vmta1  
</source>  
<source 10.0.0.0/8>  
allow-mailmerge yes  
always-allow-relaying yes  
</source>  
<source 0/0>  
allow-mailmerge no  
always-allow-relaying no  
</source>  
Above, VirtualMTA vmta1 is selected by default for any messages received through  
1.2.3.4 on the PowerMTA machine. The default listener on 0.0.0.0:25 is retained  
228  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
through its own smtp-listener directive. Permission for relaying and for using the  
mailmerge extensions is granted to connections coming from <source 10.0.0.0/8>,  
whether they connect to 1.2.3.4or not.  
8.4.4 Selecting a VirtualMTA by the Source IP  
Address  
For sites that are using applications that do not allow them to create custom X-headers  
within their messages, or for sites feeding PowerMTA messages from a variety of  
different SMTP applications and machines, PowerMTA supports the ability to select and  
use VirtualMTAs based only on the IP address of the source of the message.  
To select a VirtualMTA or VirtualMTA pool based on the IP address of the original  
source of the message, you need to;  
1. define the VirtualMTAs or VirtualMTA pools in the configuration file using the  
<virtual-mta>directive;  
2. define the specific IP address or IP address range for the source of the messages  
that is applicable using the expanded <source>directive;  
3. define the VirtualMTA to use for messages via the new default-virtual-mta  
directive within the <source>directive defined in step 2.  
For example, assuming that you had the following VirtualMTA definition in your  
configuration file:  
<virtual-mta mta1>  
smtp-source-host 1.2.3.4 mta1.port25.com  
</virtual-mta>  
and you wanted only mail coming from the local IP address 127.0.0.1 to use this  
VirtualMTA by default for each message (without having to specify an x-virtual-mta  
header in the messages), you would need to have at a minimum the following in your  
configuration file;  
<source 127.0.0.1>  
default-virtual-mta  
always-allow-relaying yes  
</source>  
mta1 # selects a VirtualMTA/pool by source of the message  
# allow feeding from 127.0.0.1  
With this, any messages submitted from the local IP address 127.0.0.1 would have  
PowerMTA using VirtualMTA mta1 and its parameters when making connections to  
deliver these messages. One can also select a VirtualMTA pool to be used for messages  
coming from the specific IP address by instead specifying a VirtualMTA pool name via  
the default-virtual-mtadirective.  
229  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
You can basically define as many different source IP addresses or IP address ranges for  
messages in the configuration file as you wish, with each using a different VirtualMTA  
or VirtualMTA pool.  
8.4.5 Selecting a VirtualMTA by a VirtualMTA IP  
address  
In addition to the above, a VirtualMTA can be slected based on which PowerMTA IP is  
used for the connection, and the corresponding VirtualMTA that is configured with that  
IP. To use this selection method, the source directive “default-virtual-mta” will need  
to be used with a setting of “by-smtp-source-ip“ in place of a VirtualMTA name.  
When configured in this way, on an inbound SMTP connection PowerMTA will use as  
the default VirtualMTA that whose "smtp-source-host" setting equals the destination IP  
address on the inbound connection.  
Example:  
<virtual-mta mta1>  
smtp-source-host 1.2.3.4 vmta1.port25.com  
</virtual-mta>  
<source 0/0>  
default-virtual-mta by-smtp-source-ip  
</source>  
In the above example, connecting to IP address 1.2.3.4 would automatically route the  
message through VirtualMTA “mta1”. Also, during the connection from the external  
mailer to PowerMTA, PowerMTA would respond with the host name configured in the  
VirtualMTA.  
8.5 Changing VirtualMTAs on the Fly  
There may be times when you need to change or even cancel a VirtualMTA definition  
after mail has already been queued for it, so PowerMTA has been designed to handle  
these scenarios.  
8.5.1 Changing a VirtualMTA  
If you change the host name and/or source IP addresses of a VirtualMTA after e-mail has  
already been queued, PowerMTA will use the new information for all new connections  
once the configuration file has been reloaded. However, if connections were already  
established when the changes are loaded, the old VirtualMTA information will be used  
for the duration of those connections.  
230  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
8.5.2 Cancelling a VirtualMTA  
If you would like to cancel a VirtualMTA after messages have already been queued, you  
can simply delete or comment its definition out of the configuration file (and run the  
pmta reload command). PowerMTA will use the new information for all new  
connections once the configuration file has been reloaded. However, if connections were  
already established when the changes are loaded, the old VirtualMTA information will be  
used for the duration of those connections.  
If a message selects a VirtualMTA which does not exist when PowerMTA attempts to  
deliver it, that message is bounced with the DSN status  
Status: 5.3.5 (specified VirtualMTA does not exist)  
8.6 Configuring Additional IP Addresses  
Before you can assign IP addresses to VirtualMTAs, they must be recognized by the  
operating system. While normally one IP address is assigned to each NIC (Network  
Interface Card), it is also possible to define additional (alias) IP addresses to an existing  
NIC.  
On Windows 2000, you add an alias IP address by opening the Control Panel, then right-  
clicking on "Local Area Connection", opening "Properties", double-clicking on "Internet  
Protocol", clicking "Advanced" and finally clicking "Add..." in the top half of the "IP  
Settings" tab. For more IPs, simply click on "Add..." multiple times, supplying the new  
IP addresses. The changes should normally become active as soon as you click on "OK"  
to close the Local Area Connection's Propertieswindow.  
On Red Hat Linux, you add an alias IP address by copying /etc/sysconfig/network-  
scripts/ifcfg-eth0 (substituting the interface name accordingly if it is not eth0) to  
ifcfg-eth0:1(in the same directory) and then edit the file, changing DEVICEto eth0:1  
and IPADDR to the new IP. If the IP address you are adding is not on the same subnet as  
the primary IP address, you may need to update NETMASKas well. You can simply delete  
the NETWORKand BROADCASTfields, if present, as they are automatically computed by the  
system. For more IPs, create additional files, named ifcfg-eth0:2, etc. To activate your  
changes, either stop and restart the interface or simply reboot the system.  
On Solaris, you add an alias IP address by creating a file named /etc/hostname.hme0:1  
(substituting the interface name if it is not hme0) and entering the desired IP address in  
that file, possibly following it with netmask or other options as required. For more IPs,  
create additional files, named hostname.hme0:2, etc. To activate your changes, reboot  
the system.  
231  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
Naturally, any IP addresses you add must be valid on the LAN to which your system is  
attached. Please consult with your network administrator if not sure what IP addresses to  
use.  
8.6.1 Adjusting your Firewall Configuration  
If PowerMTA is running on a machine behind a firewall, once it is configured to use  
diferent IP addresses for each VirtualMTA, your firewall will see outbound connection  
attempts from those IP addresses. You may need to adjust your firewall configuration  
accordingly.  
8.7 DNS Prerequisites  
Many ISPs check the host name and source IP addresses used in incoming SMTP  
connections against the information in the DNS to help determine legitimacy. Because of  
this, it is imperative that you have your DNS configured consistently with your usage of  
VirtualMTAs.  
232  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
9. Mailmerge Support  
9.1 Overview  
PowerMTA includes internal mailmerge support to maximize performance and efficiency  
in the creation, queueing, and delivery of customized e-mail messages. PowerMTA's  
mailmerge implementation (PMTA-MM) supports both simple keyword or phrase  
merging as well as merging of larger blocks of data (such as paragraphs or body parts) for  
respective recipients. Merging does not depend on the actual message contents and can  
thus be used for both text and HTML formatted messages.  
The process is basically similar to general mailmerge implementations. Your application  
generates a preformatted merge file or recipe that includes all of the recipient data  
(recipient addresses, names, order information, etc.) to be merged for each recipient,  
along with a message template. The message template includes the respective pointers to  
the variable content and data blocks to be merged in. Based on this, PowerMTA then  
creates the final merged (i.e., customized) messages for each recipient at actual delivery  
time.  
PMTA-MM is supported with all of the current mail submission methods. Mailmerge  
submissions through SMTP and the pickup directory (BSMTP) are supported through  
special protocol extensions.  
9.2 Benefits  
While PowerMTA is designed to handle the queueing and delivery of very large volumes  
of customized messages, inline mailmerge support via PMTA-MM offers additional  
performance and efficiency advantages to all components of your solution. Some the  
obvious benefits are:  
decreased responsibility and load on your CRM or e-mail marketing application  
by shifting the merging to PowerMTA;  
increased feeding performance by application to PowerMTA, given that you  
would be feeding far fewer messages to PowerMTA for the same number of  
recipients;  
increased efficiency and delivery throughput given the decrease of the I/O impact  
on your PowerMTA machine. There will be a huge decrease in the number of  
queued mail files in the spool for the same number of recipients, allowing for  
maximum scalability. For example, instead of one spool file for each recipient in  
the queue, with PMTA-MM you could have 10,000 recipients in a single spool  
file.  
233  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
9.3 Configuration Requirements  
No special configuration is needed to submit mailmerge messages through the  
submission APIs or the pickup directory. However, to use the mailmerge SMTP  
extensions, you must enable them with the allow-mailmerge directive for the IP  
address(es) from which you will be submitting the messages:  
<source 127.0.0.1>  
allow-mailmerge yes  
</source>  
9.4 Creating Mailmerge Messages  
9.4.1 Message Template and Mailmerge Variables  
Creating mailmerge messages is relatively easy. The first task is to create a message  
template, marking and labeling the portions that you would like customized for each  
recipient, like in the example below:  
(other headers omitted)  
From: shipping-confirmation@example.port25.com  
Subject: Your order #[OrderNumber] shipped!  
[First_Name],  
Your order #[OrderNumber] was shipped on [ShipTime]. Thank  
you for your  
business!  
The labels for the customized portions are names of the variables which define what  
the content for each portion.  
Once you have created your message template, you define the content for of these  
variables for the various recipients. For example, for one recipient you may want to have  
First_Name set to Bob, OrderNumber set to 1234-56 and ShipTime to 7/14 10:00. In  
the example above, this would yield:  
(other headers omitted)  
From: shipping-confirmation@example.port25.com  
Subject: Your order #1234-56 shipped!  
Bob,  
Your order #1234-56 was shipped on 7/14 10:00. Thank you for  
your  
business!  
234  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
Mailmerge variables are defined per recipient, and you cannot use the same variable  
name to define more than one set of data in the same message. Variable names are case-  
insensitive, e.g. nameand Nameare the same variable. Variable names may be composed  
of the letters (a-z and A-Z), the digits (0-9), and the underscore (_). The first character in  
a variable name must be a letter.  
As noted above, variable substitutions are enclosed in square brackets in the message  
template. To include a square bracket itself, simply write it twice. For example,  
[First_Name],  
Please fill out the fields below marked with square brackets  
[[].  
...  
would become (for a First_Name of "George")  
George,  
Please fill out the fields below marked with square brackets  
[]  
...  
9.4.2 Reserved Variables  
Variable names beginning with an asterisk are "reserved" and have a special meaning to  
PowerMTA:  
*from  
overrides the SMTP MAIL FROM (originator) address for the recipient's  
message;  
*envid  
overrides the DSN envelope ID for the recipient's message, for better tracking in  
bounces and in the accounting file. This setting overrides any other method of  
defining the envelope ID;  
*vmta  
selects the VirtualMTA (or VirtualMTA pool) through which the recipient's  
message should be delivered. This setting overrides any of the other VirtualMTA  
selection methods described in Section 8.4;  
*jobid  
defines the job (or campaign) ID for the recipient's message, for tracking in the  
WWW based monitoring facility. If set, the content of this variable overrides any  
job ID already set for the recipient's message. x-job header can be used with  
Mailmerge, but using *jobid is faster.  
*parts  
defines the list of merge parts to include in the recipient's message. For example,  
if your message has 3 parts, numbered 1, 2 and 3 and you want to include all of  
235  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
them in the recipient message, you should set *parts=1,2,3 or shorter,  
*parts=1-3. If you wanted part 3 to go before part 2 in the recipient's message,  
you would set *parts=1,3,2;  
*to  
merges in the defined RCPT TO/recipient e-mail address. This variable is  
automatically set from the recipient address and cannot be overridden;  
*date  
merges in the message's reception date & time stamp. This variable is  
automatically set and cannot be overridden;  
9.4.3 Merge Parts  
Each message template is made up of one or more sections called merge parts. A merge  
part can be a sentence, a paragraph, a block of paragraphs, a body part, or even the  
message headers. Within each merge part there can be many mailmerge variable  
substitutions.  
The parts or sections of the message are labelled with a part number, and then assembled  
for each recipient based upon the content of the special *partsvariable for the recipient.  
For example, a travel alerts service could send messages in three parts: the first  
containing the headers and a common preamble,  
From: "Customer Service" [*from]  
To: "[FName]" [*to]  
Date: [*date]  
Subject: Travel Plans  
Dear [FName],  
You are flying out of [Airport] given that it is closest to  
your location  
in [City], [State].  
the second containing a notice that is only sent to some of the recipients,  
With this flight, you are only [MilesToBonus] frequent flyer  
miles away from  
your next SuperBonus(TM)!  
the third with a common final block:  
Have a great trip!  
Some recipients could then be sent all parts (*parts=1-3) while others would only be  
sent parts #1 and #3 (*parts=1,3). Note that the variable MilesToBonus would only  
need to be defined for those recipients receiving part #2.  
236  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
9.5 Submitting Mailmerge Messages  
You can feed mailmerge messages to PowerMTA using any the standard supported  
submission APIs, pickup directory, or through PowerMTA's mailmerge SMTP  
extensions. It is recommend to add no more than 5000 recipients per mail merge file  
when feeing via pickup directory.  
9.5.1 API Submission  
All PowerMTA submission APIs include support for mailmerge. The basic process  
involves defining per-recipient variables by invoking the defineVariable for each  
Recipientobject, and then passing the message template by invoking the addMergeData  
method for the Messageobject. Please refer to the corresponding API reference for more  
details.  
Sample programs for using mailmerge in the APIs are provided with PowerMTA.  
9.5.2 Mailmerge SMTP extensions  
Port25 has extended the SMTP protocol for sites that would prefer to feed PowerMTA  
mailmerge messages via a modified SMTP interface.  
The mailmerge extensions define three new verbs:  
XMRG  
Replaces the MAIL command of a standard SMTP submission. All extensions  
(such as DSN, VERP, etc.) that are supported with MAIL are also supported with  
XMRG.  
Example:  
XMRG FROM:<travelAlerts@example.port25.com> VERP  
XDFN  
Defines variables for the recipient following it. One or more XDFN commands  
should be issued prior to each RCPTcommand in a mailmerge submission.  
Variables are defined in the format name=value, where name is the variable name  
and value the value to to be associated with the variable. If the value contains any  
white space, it should be enclosed in double quotes. You can specify multiple  
variables in a single XDFNcommand by separating them with blanks.  
Example:  
237  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
XDFN name="Bob Example" Airport=BWI  
XDFN *jobid="TravelAlerts"  
RCPT TO:<bob@example.port25.com>  
XPRT  
Replaces the DATA command of a standard SMTP submission. One XPRT  
command should be issued per merge part in the mailmerge submission, passing  
the merge part number, like in the example below:  
XPRT 1  
Like for DATA, PowerMTA responds to the XPRTcommand with a 3xx reply code.  
Also, like data, the message template must be passed dot-escaped. A dot on a line  
by itself terminates the merge part.  
The last XPRT is indicated with the additional LAST parameter and terminates the  
submission:  
XPRT 2 LAST  
The following example shows all the three verbs used to submit a mailmerge to two  
recipients. In addition to parts 1 and 3, Alice is also sent part #2 with a reminder that  
she's close to obtaining a bonus:  
XMRG FROM:<travelAlerts@example.port25.com> VERP  
XDFN FName="Alice" Airport="IAD" MilesToBonus="120"  
XDFN City="Herndon" State="VA" *parts=1-3 *vmta="mta4"  
XDFN *jobid="TravelAlerts"  
RCPT TO:<alice@example.port25.com>  
XDFN FName="Bob" Airport="BWI"  
XDFN City="Ellicott City" State="MD" *parts=1,3 *vmta="mta5"  
XDFN *jobid="TravelAlerts"  
RCPT TO:<bob@example.port25.com>  
XPRT 1  
From: "Customer Service" [*from]  
To: "[FName]" [*to]  
Date: [*date]  
Subject: Travel Plans  
Dear [FName],  
You are flying out of [Airport] given that it is closest to  
your location  
in [City], [State].  
.
XPRT 2  
With this flight, you are only [MilesToBonus] frequent flyer  
miles away from  
your next SuperBonus(TM)!  
.
238  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
XPRT 3 LAST  
Have a great trip!  
.
9.5.3 Pickup Directory Submission  
The pickup directory submission method includes support for mailmerge, which greatly  
minimizes the disk I/O impact usually associated with this submission method. Instead of  
creating and writing 100,000 messages, one per recipient, mailmerge support allows you  
to write say only 25-50 files for the same number of recipients, greatly minimizing the  
resources utilized and increasing throughput. Section 7.4 covers the pickup directory  
more in detail.  
Support for mailmerge in the pickup directory is accomplished through its support for  
BSMTP (batched SMTP) files. See Section 7.4.1 for more information.  
Here is a simple example of a properly formatted BSMTP mailmerge file for  
PowerMTA's pickup directory:  
XMRG FROM:<bounce@port25.com>  
XDFN *from="blahblah@port25.com"  
XDFN subject="BSMTP mailmerge format"  
RCPT TO:<bob@port25.com>  
XPRT 1 LAST  
From:  
To:  
[*from]  
[*to]  
Subject: [subject]  
Hello [*to]!  
.
Here is another that contains information for 4 recipients:  
XACK ON  
XMRG FROM:<bounce@port25.com> verp  
XDFN FName="Jim" FavFood="pizza" Car="minivan" CID="1234"  
XDFN *vmta="mta1" *parts="1-3" *jobID="1234"  
RCPT TO:<jim@test.port25.com>  
XDFN FName="Tim" FavFood="sushi" Car="porsche" CID="2345"  
XDFN *vmta="mta2" *parts="1,3,2" *jobID="5678"  
RCPT TO:<tim@test.port25.com>  
XDFN FName="Cosmo" Car="Gremlin" CID="3456"  
XDFN *vmta="mta3" *parts="1,3" *jobID="1234"  
RCPT TO:<cosmo@test.port25.com>  
XDFN FName="Frank" FavFood="pizza" CID="4567"  
XDFN *vmta="mta5" *parts="1,2" *jobID="5678"  
RCPT TO:<frank@test.port25.com>  
XPRT 1  
239  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
X-CID: [CID]-abc  
From: "Customer Service" [*from]  
To: "[Fname]" [*to]  
Subject: Travel Plans  
Date: [*date]  
Hey [FName],  
.
XPRT 2  
Your favorite food is [favfood].  
.
XPRT 3 LAST  
You drive a [car].  
.
Section 9.5.2 also provides another good example for reference.  
Here is an example of a multi-part mailmerge file for a pickup directory:  
XMRG FROM:<me@yourdomain.com> verp  
XDFN *from="me@yourdomain.com"  
XDFN subject="test \ 1"  
RCPT TO:<you@yourdomain.com>  
XDFN *from="me@yourdomain.com" subject="test 2"  
RCPT TO:<you@yourdomain.com>  
XPRT 1 LAST  
Mime-Version: 1.0  
Content-Type: multipart/alternative; boundary="12345"  
From:  
To:  
[*from]  
[*to]  
Subject: [subject]  
--12345  
Content-Type: text/plain;  
Hello. This is the text version.  
--12345  
Content-Type: text/html;  
<b>This is the HTML version.</b>  
--12345--  
.
9.5.4 The XACK SMTP extension  
To facilitate and improve the feeding performance while using the mailmerge extensions,  
Port25 has also defined the XACKprotocol extension.  
240  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
The XACK command disables acknowledgements for the RCPT and XDFN commands. It  
accepts a single, parameter, either ON or OFF. To disable acknowledgements, you issue  
XACKlike in the example below:  
XACK OFF  
Once acknowledgements are disabled, they stay disabled until the connection is closed or  
until they are re-enabled with XACK ON.  
While acknowledgements are disabled, any errors occurring as a result of RCPT or XDFN  
command during a submission (i.e., after MAIL or XMRG and before the final  
DATA/BDAT/XPRTcommand) are reported as a response to the next DATAor BDAT(for non-  
mailmerge messages) or XPRT (for mailmerge messages). As a result of the error, the  
entire submission is cancelled.  
Some errors (e.g., address errors in the RCPT) may optionally be reported by sending a  
failure Delivery Status Notification, thus allowing the submission to continue. Any RCPT  
or XDFN errors (e.g., out of sequence errors) occurring not during a submission are  
ignored entirely.  
The following example shows the connection trace (with commands and replies, but with  
the message content omitted) while submitting a mailmerge message:  
241  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
>>> 220 mailhost.port25.com (PowerMTA v2.x) ESMTP service ready  
<<< EHLO test.port25.com  
>>> 250-mailhost.port25.com says hello  
>>> 250-ENHANCEDSTATUSCODES  
>>> 250-PIPELINING  
>>> 250-CHUNKING  
>>> 250-8BITMIME  
>>> 250-XACK  
>>> 250-XMRG  
>>> 250-SIZE 0  
>>> 250-VERP  
>>> 250 DSN  
<<< XACK OFF  
>>> 250 2.0.0 ok  
<<< XMRG FROM:<bounce@example.port25.com> verp  
>>> 250 2.1.0 XMRG ok  
<<< XDFN FName="Jim" FavFood="pizza" Car="minivan" CID="1234" *vmta="vmtapool" *parts="1-3"  
<<< RCPT TO:<jim@example.port25.com>  
<<< XDFN FName="Tim" FavFood="sushi" Car="porsche" CID="2345" *vmta="vmta2" *parts="1,3,2"  
<<< RCPT TO:<tim@example.port25.com>  
<<< XDFN FName="Cosmo" Car="Gremlin" CID="3456" *vmta="vmta3" *parts="1,3"  
<<< RCPT TO:<cosmo@example.port25.com>  
<<< XDFN FName="Frank" FavFood="pizza" CID="4567" *vmta="vmta1" *parts="1,2"  
<<< RCPT TO:<frank@example.port25.com>  
<<< XPRT 1  
>>> 354 send part  
<<< .  
>>> 250 2.6.0 part ok  
<<< XPRT 2  
>>> 354 send part  
<<< .  
>>> 250 2.6.0 part ok  
<<< XPRT 3 LAST  
>>> 354 send part  
<<< .  
>>> 250 2.6.0 message received  
<<< QUIT  
>>> 221 2.0.0 mailhost.port25.com says goodbye  
242  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
10. Advanced Features  
10.1 Sender Reputation Monitoring  
10.1.1 Overview  
One of the keys to maximizing deliverability to valid domains is to know as soon as  
possible when specific delivery problems are occurring. The sooner one realizes that  
there are certain problems, or more specifically, that a remote site is rejecting your  
messages for one reason or another, the sooner one can attempt to get the problems  
resolved. There are many different kinds of errors that remote sites can respond with  
when connected, both positive and negative, and these responses allow you to see first  
hand your current sender reputation, in the eyes of that recipient domain or mail gateway.  
Given the importance of having this information as soon as possible, PowerMTA v3.0  
includes automated sender reputation monitoring, via an advanced, real time SMTP  
command monitoring implementation. It not only gives you an early warning alert system  
for specific types of errors, but it can be configured to try and possibly resolve some  
problems as well, via support for automated configuraton changes for future delivery  
attempts.  
10.1.2 Implementation  
For greatest flexibility and control, PowerMTA groups messages for a particular domain  
for a particular VirtualMTA in its own queue. Sender reputation monitoring provides real  
time monitoring of defined SMTP responses (e.g., "551 Sender IP rejected") from remote  
hosts for each queue, with the ability to define certain actions (e.g., send an e-mail alert  
while throttling deliveries) upon a match.  
This is accomplished through the introduction of queue "modes". The two modes initially  
supported are "normal" and "backoff". You can configure PowerMTA so that, when a  
queue enters backoff mode, it  
sends an email alert to one or more addresses (backoff-notifydirective);  
dynamically changes the retry schedule for that queue (backoff-retry-after  
directive);  
dynamically applies per-queue delivery throttling (backoff-max-msg-per-hour  
directive);  
dynamically reroutes the messages from one VirtualMTA to another VirtualMTA  
(backoff-reroute-to-vmtadirective).  
243  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
       
The dynamic reroute, combined with the ability to now have separate per domain  
configurations per VirtualMTA, allows one to use the full range of domain directives  
beyond the new backoff-... directives (e.g., using a new bounce-after), as well as  
VirtualMTA attributes, for the fallback queue. A chain of backoff VirtualMTAs is also  
supported (vmta -> vmta1, vmta1 -> vmta2, vmta2 -> vmta3, etc.).  
SMTP response matching is performed based on a list of perl-compatible regular  
expressions, entered in a smtp-pattern-listdirective in the configuration file.  
For example, you could define a list of errors that might occur during deliveries to AOL  
in a smtp-pattern-list named aol-errors, and specify that the queue be put in  
backoff mode if any such match:  
<smtp-pattern-list aol-errors>  
reply /generating high volumes of.* complaints from AOL/  
mode=backoff  
reply /Excessive unknown recipients - possible Open Relay/ mode=backoff  
reply /^421 .* too many errors/  
reply /blocked.*spamhaus/  
reply /451 Rejected/  
mode=backoff  
mode=backoff  
mode=backoff  
</smtp-pattern-list>  
You would then indicate that PowerMTA should match based on that pattern list while  
delivering to aol.com:  
<domain aol.com>  
...  
smtp-pattern-list aol-errors  
...  
</domain>  
Finally, also within that domaindefinition, you would specify certain backoff-... actions  
to be taken when the queue enters backoff mode:  
<domain aol.com>  
...  
smtp-pattern-list  
aol-errors # SMTP response pattern list to use  
backoff-max-msg-per-hour 120  
# 10 messages per 5 min interval  
# retry every hour  
backoff-retry-after  
backoff-notify  
...  
1h  
postmaster@yourdomain.com  
</domain>  
Upon the first match of the SMTP response, the queue for aol.com for this particular  
VirtualMTA will enter backoff mode, dynamically applying the specific backoff-...  
directives:  
send an email alert to the defined PowerMTA postmaster address;  
change the retry interval to aol.comfor this particular VirtualMTA to 1 hour;  
throttle the delivery rates to aol.com for this particular VirtualMTA to at most  
120 attempted deliveries per hour;  
244  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
The backoff directives apply until the mode for the queue is returned to normal, which  
can be accomplished either within a smtp-pattern-list(by specifying a mode=normal  
for a pattern), with the pmta set queue command, or by restarting PowerMTA. In the  
example above, the command to return that queue to normal mode would be  
pmta set queue --mode=normal aol.com  
Defining backoff VirtualMTAs is also relatively straightforward, using the backoff-  
reroute-to-vmtadirective. It simply specifies that PowerMTA should reroute messages  
to the given VirtualMTA in case the queue enters backoff mode.  
For example, if messages are queued for example.port25.com/vmta1 and that queue  
enters backoff mode while backoff-reroute-to-virtual-mtais set to vmta2, all of its  
messages would be rerouted to the queue example.port25.com/vmta2. Since the  
messages would then be queued within vmta2, that VirtualMTA's settings would apply.  
New messages entering the queue are also immediately rerouted to the new VirtualMTA,  
as long as the vmta1queue remains in backoff mode.  
For example, one could define a backoff VirtualMTA as follows:  
<virtual-mta mta1>  
smtp-source-host 1.1.1.1 mta1.port25.com  
<domain *>  
backoff-reroute-to-vmta backoff-mta1  
smtp-pattern-list  
</domain>  
block-errors  
</virtual-mta>  
<virtual-mta backoff-mta1>  
smtp-source-host 1.1.1.2 mta2.port25.com  
<domain *>  
retry-after 30m  
bounce-after 1h  
</domain>  
</virtual-mta>  
With this, if there is an SMTP pattern match for any domain for VirtualMTA mta1, any  
messages in that specific queue will be delivered using the domain directives and  
VirtualMTA parameters defined in VirtualMTA backoff-mta1. As desired, the backoff  
parameters will only apply to messages for the specific queue, that is, for messages in the  
queue whose delivery attempts matched a SMTP response.  
Note that since the messages are really transferred from one VirtualMTA to another, the  
backoff-reroute-to-vmta directive effectively takes precedence over backoff-max-  
msg-per-hourand backoff-retry-after.  
245  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
10.1.3 Supporting commands  
Two new command line commands have been added to facilitate working with sender  
reputation monitoring and queue modes:  
pmta set queue --mode={normal|backoff} domain/vmta  
pmta show queues  
The set queue command sets the given queue's mode of operation to either normal or  
backoff. See Section 6.3.11 for more information.  
The show queues command allows you to view current information on the specified  
queues, including the current mode of the queue. See Section 6.3.13 for more  
information.  
10.2 SMTP AUTH support  
10.2.1 Overview  
To facilitate creating a secure email delivery channel, PowerMTA supports  
authentication in both inbound and outbound SMTP connections.  
10.2.2 Implementation for Inbound Connections  
PowerMTA supports authentication with either the PLAINor the CRAM-MD5mechanism in  
inbound connections, with the DIGEST-MD5 mechanism being considered for a future  
version. Support for CRAM-MD5 is available whenever AUTH itself is enabled. Since  
PowerMTA does not yet support encryption of connections and using the PLAIN  
mechanism would involve sending passwords unencrypted over the Internet, support for  
it must be explicity enabled with the allow-unencrypted-plain-auth directive. The  
password is never sent when using CRAM MD, as it's a challenge/response  
authentication.  
To use AUTH you must also create <smtp-user> tag for each valid username, including  
their passwords, as well as the named source to use when that user authenticates, like in  
the example below:  
246  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
       
<smtp-user jsmith>  
password qwerty123  
source {auth2}  
</smtp-user>  
<smtp-user jdoe>  
password abc123  
source {auth1}  
</smtp-user>  
For maximum flexibility in supporting the various SASL authentication methods, the  
passwords must be entered in plaintext. Because of this, it is crucial that the file  
permissions are set up as restrictively as possible. Port25 intends to look into ways to  
encrypt the passwords in a future release.  
The "named" source in the configuration file (that is a <source> entry that has a name  
rather than an IP address or CIDR specification), allows you to specify which <source>  
settings should apply on a per-user basis.  
In the example above, and with the configuration file below, user jsmith would be  
allowed access to PowerMTA's mail merge extensions, while jdoewould not:  
<source {auth2}>  
allow-mailmerge yes  
always-allow-relaying yes # allow feeding for {auth2}  
process-x-virtual-mta yes # allow selection of a VirtualMTA  
max-message-size 0  
smtp-service yes  
require-auth true  
</source>  
# 0 implies no cap, in bytes  
# allow SMTP service  
<source {auth1}>  
allow-mailmerge no  
always-allow-relaying yes # allow feeding for {auth1}  
process-x-virtual-mta yes # allow selection of a VirtualMTA  
max-message-size 0  
smtp-service yes  
require-auth true  
</source>  
# 0 implies no cap, in bytes  
# allow SMTP service  
<source 0/0>  
allow-unencrypted-plain-auth yes  
</source>  
When users jsmith and jdoe authenticate, any settings in their named sources would  
override those settings normally obtained based on each connections' source IP address.  
This way, you can combine the usual IP-based settings (which apply to all connections)  
with specific settings based on the authenticated user.  
247  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
See Section 3.2.4 for more details on SMTP service directives.  
10.2.3 Implementation for Outbound Connections  
PowerMTA supports authentication with the CRAM-MD5, LOGIN, or PLAINmechanisms  
in outbound connections, with additional mechanisms being considered for a future  
version.  
To have PowerMTA authenticate to a remote mailer when delivering messages to a  
domain, define the domain in the configuration file and specify the auth-username and  
auth-password directives. Authentication will be attempted only if the remote mailer  
supports CRAM-MD5, LOGIN, or PLAIN (LOGIN or PLAIN if using the <domain>  
directive “use-unencrypted-plain-auth yes”).  
To illustrate how this feature could be used, consider the following scenario: an email  
service provider using PowerMTA is delivering email on behalf of, and thus "from"  
secure.example.org, but that domain's corporate mail system will only accept mail  
using that domain as the originator from an authenticated source.  
To satisfy the corporate mail system's requirement, one could configure PowerMTA to  
select a VirtualMTA based on pattern matching of the From: address (using the support  
for pattern matching of any RFC 2822 header), and within that VirtualMTA, configure  
the required username and password for all mail delivered to secure.example.org.  
The VirtualMTA definition could look like:  
<virtual-mta auth-mta>  
smtp-source-host 1.2.3.4 vmta.esp.com  
...  
<domain secure.example.org>  
auth-username costanza  
auth-password bosco  
</domain>  
</virtual-mta>  
With this, all mail delivered by this VirtualMTA to the domain of secure.example.org  
would attempt authentication, whereas all other mail delivered to this domain by other  
VirtualMTAs would not.  
Note that authentication is not attempted if auth-username and auth-password are not  
defined for a domain.  
10.3 Sender-ID support  
248  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
10.3.1 Overview  
PowerMTA v3.0 includes automatic support for the Sender-ID Framework backed by  
Microsoft, as it relates to the sending of authenticated e-mail. Sender-ID is a specification  
created to counter e-mail domain spoofing and to provide greater protection against  
phishing schemes. It helps verify that each e-mail message comes from a particular  
domain from which it claims to come, based on the IP address of the sending server.  
More  
information  
about  
Sender-ID  
can  
be  
found  
at  
http://www.microsoft.com/mscorp/safety/technologies/senderid/default.mspx.  
10.3.2 Automated Authentic  
To help maintain a strong sender reputation, PowerMTA can be configured to force  
Sender-ID compliance, by only delivering mail that is Sender-ID compliant.  
PowerMTA v3.0 includes the ability to automatically check each mail submitted to make  
sure that it is Sender-ID compliant before delivery is attempted. Compliance checking is  
done based on the sender address, the source IP address to be used in the connection, and  
the SPF 2.0 records published in the DNS. The sender address used depends on the scope  
of the test being made: both the "pra" (Purported Responsible Address, based on message  
headers) and the "mfrom" (based on the SMTP MAIL FROMand HELOdomains) scopes are  
supported. Other compliance checks, such as for DomainKeys are being considered.  
If the test results in anything but a "Pass" or a "TempError", the message bounces, with  
an appropriate bounce sent to the MAIL FROMaddress.  
To enable Automated Authentic for a domain, set the check-mfrom-outbound and  
check-pra-outbounddirectives to yesin the domain's defintion in the configuration file  
(or in <domain *>for all domains).  
When enabling this feature, it is advisable to disable it for the domains to which your  
bounces are delivered, if they are delivered via SMTP. This way, if the Sender-ID check  
fails, there is no risk of these bounces being lost ("double-bouncing") due to some  
problem in your bounce domain's SPF records.  
For example, if your MAIL FROM domain was yourbouncedomain.com, you could  
configure:  
<domain yourbouncedomain.com>  
check-mfrom-outbound no  
check-pra-outbound no  
</domain>  
<domain *>  
check-mfrom-outbound yes  
249  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
check-pra-outbound yes  
</domain>  
Note that since a specific IP address is needed for the Automated Authentic check, you  
will need to make sure that the IP address(es) used by PowerMTA for outbound  
connections are defined in the configuration file (via the smtp-source-hostdirective). If  
no specific source IPs are defined, PowerMTA cannot perform the Sender-ID check. It  
then generates an error message in the log file and treats this like a transient ("4xx") error,  
keeping the messages in the queue and retrying until the bounce-afterinterval passes.  
10.3.3 SUBMITTER Optimization  
PowerMTA v3.0 senses when the new SUBMITTER extension is supported by the  
receiving mailer and automatically computes the message's PRA and passes it on, so that  
the authentication check can be performed before the message content is transferred.  
Since both detection and PRA computation are performed automatically, no  
configuration is necessary to activate this feature. It is always active when applicable.  
10.4 DomainKeys/DKIM support  
10.4.1 Overview  
Port25 Solutions is one of the first companies to support an early implementation of  
"DomainKeys" and the later revision, DKIM, the e-mail sender authentication scheme  
backed by Yahoo! based on cryptographically signing e-mail messages. Port25 highly  
recommends that all users looking to use this functionality read through the DomainKeys  
& DKIM specification currently found here:  
http://domainkeys.sourceforge.net/ & http://www.dkim.org/.  
Here is a brief description of how an email is signed with DomainKeys & DKIM:  
1. A public/private key pair is generated for use for signing all outgoing messages;  
2. The public key is published in DNS, and the private key is made available to the  
outbound email servers;  
3. When a message is submitted for delivery, the email system uses the stored  
private key to generate a digital signature of the message before delivery and adds  
it to the message in the DomainKey-Signature:header.  
250  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
10.4.2 PowerMTA's DomainKeys/DKIM  
Implementation  
PowerMTA supports DomainKeys & DKIM signing of email on a per VirtualMTA or a  
global basis. That is, within each <virtual-mta> definition you can specify a domain  
key to use. Alternatively, domain keys can be configured at the global level and they will  
be used by any VirtualMTA's. The new directive is named domain-key and takes three  
arguments: the DomainKeys selector, the domain (or parent domain) from which  
messages will originate, and the name of the file containing the private key. For example:  
<virtual-mta domainkey>  
host-name port25.com  
...  
domain-key test,port25.com,c:\pmta\test.port25.pem  
</virtual-mta>  
or  
domain-key test,port25.com,c:\pmta\test.port25.pem  
You can specify multiple domain-key entries. PowerMTA determines the key to use by  
going through the keys sequentially and picking the first key whose domain either equals  
or is a parent of the message's sending domain. If there are keys that match at both the  
global level and the VirtualMTA level, the <virtual-mta> domain keys will be used.  
The sending domain is that of the Senderheader, or, if Senderis not present, of the From  
header. If no keys match the sending domain, the message is not signed.  
For DKIM, if the sender or from headers are not able to be set or changed (e.g. An ESP  
customer’s email that cannot be changed), use of the dkim-identity <domain> directive  
allows for specifying a domain or email address to be used for the signing and  
authentication in place of the sender or from header. Using dkim-identity sets the i=  
value in the DKIM signature to the value specified in with dkim-identity, and the d=  
value to that set by the domain-key directive. Use of this directive will not affect  
message signed with DomainKeys.  
To set up DomainKeys/DKIM signing for a domain,  
1. if this is your first domain key, define the _domainkeyTXT record in your DNS,  
specifying your DomainKeys policy:  
_domainkey.example.org. 1D IN TXT "t=y\; o=~\;"  
2. Please do not use the example above unchecked; refer to the DomainKeys  
specification for more information on the policy record syntax.  
251  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
3. Determine the domain in which the key will be registered. That should be either  
the domain itself or a parent of the sending domain. In the examples below, we  
will assume example.org.  
4. Decide what to use for your selector. The selector will uniquely identify the key  
within the domain determined above. We will use k1in the examples below.  
5. Generate your private key using the port25 DomainKey wizard:  
http://www.port25.com/support/support_dkwz.php  
(If using the wizard, skip step 8)  
or use openssl:  
openssl genrsa -out k1.example.pem 1024  
6. This creates a 1024-bit private key in the file k1.example.pem. You can use any  
other file name, as long as you modify the following steps accordingly;  
7. Move that file to c:\pmta\on Windows or to /etc/pmtaon Unix and ensure its  
permissions are set properly (ideally only PowerMTA should have access to it).  
8. Generate a public key from your private key:  
openssl rsa -in k1.example.pem -out public.pem -pubout  
9. Define a TXT record in the DNS for the domain key, using the public key  
generated in the last step in the ptag:  
K1._domainkey.example.org 1D IN TXT "k=rsa\; p=MIGfMA0...\;"  
10. Please refer to the DomainKeys specification for more information on the record  
syntax.  
11. Add the domain-keydirective to the config file:  
<virtual-mta example>  
...  
domain-key k1,example.org,c:\pmta\k1.example.pem  
</virtual-mta>  
12. or  
domain-key k1,example.org,c:\pmta\k1.example.pem  
or  
domain-key k1,*,c:\pmta\k1.example.pem  
252  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
13. Enable signing for the domain(s) desired, or in <domain *>to enable signing for  
all domains:  
<domain yahoo.com>  
...  
dk-sign yes  
dkim-sign yes  
</domain>  
14. If the domain-key directive is configure for a VirtualMTA instead of globally,  
configure PowerMTA so that email originating in the domain(s) to be signed  
select that VirtualMTA, for example, by using a pattern list:  
<pattern-list L>  
mail-from /[@\.]example\.com$/ virtual-mta=example  
</pattern-list>  
<source 10.1.0.0/16> # feeding sources  
pattern-list L  
</source>  
15. See Chapter 8 for more information on selecting VirtualMTAs. Section 3.2.16  
describes pattern lists in greater detail.  
10.4.3 DKIM signing based on values in a header  
PowerMTA supports the ability to sign messages with DKIM using values passed in the  
header x-dkim-options. This header may contain the selector, domain, or identity used  
for DKIM signing:  
x-dkim-options: <semicolon separated list of options>  
Options:  
s - selector- can be any value other than empty string  
d - domain - should be a domain  
i - identitiy - can be a complete email address or an email address minus the local  
part (e.g. @example.com).  
To use this header, one must specify either i or d. If both are specified, the value of d will  
be used to select amongst the keys, and not i. In addition, the value of s can be specified  
as the selector. If i or d is specified, it will be treated as the identity to look up the key. If  
neither is specified, PMTA will use the current method of key selection (sender-or-from).  
If s is specified, only the key with the matching selector among the list of keys matching  
253  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
the identity will be used to sign. If no such key for the selector is found, the email is not  
signed. The order in which options are specified is not important.  
For Example, with the following configuration:  
domain-key key1,example.com,c:\pmta\key1.example.com.pem  
The x-dkim-options header will have to specify s=key1 and d=example.com (or specify  
an i with the same domain, or a subdomain) :  
x-dkim-options: s=key1;d=example.com  
or  
x-dkim-options: s=key1;i=example.com  
It is important to note that if a value for d is specified, then only the key with the EXACT  
domain or the first key which matches every every domain ('*') will be used. Keys for  
subdomains are not used for signing such emails. Also, note that x-dkim-options  
overrides dkim-identity, so dkim-identity is not used if either d or i values are specified  
in the x-dkim-options header.  
Lastly, dkim-identity-fallback is used as the fallback key to sign with if no matching  
key has been found, irrespective of whether x-dkim-options or dkim-identity was used  
to specify the identity to sign with.  
10.5 Warming of IPs with Cold VirtualMTA  
10.5.1 Overview  
When starting to send email from a new IP address, it is sometimes important to control  
the amount of traffic sent from that IP, so that reputation can be built properly. To  
facilitate this task, PowerMTA adds support for automatically configuring separate  
queues and diverting part of the traffic to those queues.  
This is configured by adding a "auto-cold-virtual-mta" directive within an existing  
VirtualMTA, passing the new IP address and the host name associated with that IP  
address. The directive instructs PowerMTA to dynamically create, in memory, a new  
VirtualMTA with a name of "existingVMTAname-cold".  
With this in place, on a per-domain basis (globally or per-vmta, or any mixture of these) a  
traffic limit is set with "max-cold-virtual-mta-msg N/day". Please note that this setting is  
per domain, so 1000 emails will go to yahoo, 1000 will go to hotmail, etc. The default of  
that is 0, which means "don't re-select a cold vmta". If the limit is set globally but the  
254  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
VirtualMTA selected doesn't have a "cold-virtual-mta" directive configured, no re-  
selection takes place.  
An example of this setup would be as follows:  
<virtual-mta customer1>  
...  
auto-cold-virtual-mta COLDIP HOSTNAME  
...  
<domain *>  
max-cold-virtual-mta-msg 1000/day  
</domain>  
</virtual-mta>  
In the above example, COLDIP is the cold IP and HOSTNAME is the hostname  
corresponding to it. This will send the first 1000 messages queued to the VirtualMTA to  
the dynamically created customer1-cold VirtualMTA, and then send the remaining  
messages to the VirtualMTA customer1.  
Cold vmta re-selection takes place during feeding, so you'll need to feed in more  
messages daily if you want to ensure the limit gets used up. The counters are reset at  
midnight.  
Re-selection can be used with pools, too. In that case the next vmta in the pool is first  
selected and, if below the limit, re-selection takes place.  
Both the limits and the selection are persisted on disk, so that you can safely re-start  
PowerMTA.  
You can also define the cold VirtualMTA manually. This may be helpful in managing  
the settings of the cold VirtualMTA instead of letting PowerMTA use the default settings.  
This setup uses the cold-virtual-mta directive (instead of auto-cold-virtual-mta) and takes  
the name of the manually defined cold VirtualMTA.  
255  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
An example of this setup would be as follows:  
<virtual-mta customer1>  
...  
cold-virtual-mta COLD-VMTA-NAME  
...  
<domain *>  
max-cold-virtual-mta-msg 1000/day  
</domain>  
</virtual-mta>  
<virtual-mta COLD-VMTA-NAME>  
...  
smtp-source-host COLDIP HOSTNAME  
...  
</virtual-mta>  
10.6 Using of Bounce Category Patterns  
10.6.1 Overview  
This directive makes the bounce categories used in CSV accounting files and the X-  
PowerMTA-BounceCategory DSN field customizable (binary files still use the built-in  
categories). A customer can specify the tag in the configuration file, in which case the  
patterns specified there take precedence over those defined in config-defaults file. The  
data in the <bounce-category-patterns> tag consist of two fields. The first field is the  
SMTP response on which to match, and the second field is the name of the category to be  
used. Custom category names are allowed. It should be entered in a <bounce-category-  
patterns> entry, like in:  
<bounce-category-patterns>  
/spam/ spam-related  
/no longer (valid|available)/ bad-mailbox  
/mailbox +(is +)?full/ quota-issues  
/banned/ policy-related  
</bounce-category-patterns>  
<bounce-category-patterns> uses pattern matching in the same method as  
does <pattern-list>. Section 3.2.16 describes SMTP pattern lists and  
pattern matching in greater detail.  
256  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
10.7 Combining domains with the same MX record(s)  
into one queue  
10.7.1 Overview  
PowerMTA has the ability to group together email domains if they share the same MX  
records. This can be useful for controlling the message stream across multiple domains.  
This includes any <domain> based controls such as max-msg-rate, max-smtp-out, and  
max-connect-rate.  
The directive to use is "queue-to", which is defined in the <domain> definitions that you  
want to rollup. The parameter defined within the queue-to directive is the name of the  
"domain" that the other domains will be rolled up into. Use of the route directive is  
required. The route directive should point to the root domain to which mail should be  
delivered.  
For example:  
#
<virtual-mta queue-rollup>  
<domain hotmail.rollup>  
max-smtp-out 10  
route hotmail.com  
</domain>  
<domain hotmail.com>  
queue-to "hotmail.rollup"  
</domain>  
<domain hotmail.co.uk>  
queue-to "hotmail.rollup"  
</domain>  
<domain live.com>  
queue-to "hotmail.rollup"  
</domain>  
</virtual-mta>  
#
With this, all messages queued for this VirtualMTA for any hotmail.com, hotmail.co.uk,  
or live.com domain will be put in one queue named "hotmail.rollup", and treated as such.  
257  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
Or:  
#
<virtual-mta client-mta>  
hostname mail1.yourdomain.com  
smtp-source-ip 1.2.3.4  
<domain [*.]psmtp.com>  
queue-to "psmtp.com"  
max-smtp-out 20  
bounce-after 2d  
max-msg-per-connection 10  
</domain>  
</virtual-mta>  
With this, all messages queued for this VirtualMTA for any psmtp.com domain (e.g.  
mail9.psmtp.com, someone.psmtp.com, etc.) will be put in the one queue for psmtp.com,  
and treated as such. This also offers the flexibility to pick and choose which  
domains/subdomains to roll up into the one domain, or to roll up all domains, by having  
the queue-to defined within <domain *> in the VirtualMTA. As a note, if you are using  
a cold VirtualMTA, the directive max-cold-virtual-mta is applied BEFORE queue-to is  
applied.  
258  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Use of the naming convention domainname.rollup is strongly advised, as this will allow  
for faster reporting in PowerMTA Management Console. Examples are:  
hotmail.rollup  
yahoo.rollup  
aol.rollup  
gmail.rollup  
google.rollup  
kpn.rollup  
ziggo.rollup  
upc.rollup  
versatel.rollup  
xs4all.rollup  
wanadoo-nl.rollup  
wanadoo-uk.rollup  
tiscali-nl.rollup  
messagelabs-eu.rollup  
zeelandnet.rollup  
skynet.rollup  
yahoo-eu.rollup  
postini.rollup  
frontbridge.rollup  
gmx.rollup  
terra.rollup  
scarlet.rollup  
orange-fr.rollup  
web-de.rollup  
caiway.rollup  
tele2.rollup  
t-online.rollup  
onet-pl.rollup  
roadrunner.rollup  
roadrunner2.rollup  
roadrunner3.rollup  
roadrunner-biz.rollup  
netease.rollup  
259  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
10.8 Setting recipient priority  
10.8.1 Overview  
It may be necessary to set a given recipient of set of recipients with a higher or lower  
priority (e.g. password reset vs. weekly newsletter).  
This can be facilitated in  
PowerMTA by a couple different means. The first is via the <domain> directive “queue-  
priority”. The directive works in the following manner:  
<domain someplace.com>  
queue-priority 75  
</domain>  
<virtual-mta newsletter>  
<domain someplaceelse.com>  
queue-priority 30  
</domain>  
</virtual-mta>  
With the above set, all messages going to someplace.com will get a queue-priority of 75  
(the default is 50 with a range of 1-100, higher amounts being given higher priority).  
This will give this set of messages first priority in PowerMTA for connections and  
delivery. The messages for someplaceelse.com/newsletter will get a lower priority than  
the average mail, and will go out last.  
Another method of setting the message priority is by using a <pattern-list>. The directive  
works in the following manner:  
<pattern-list myList>  
rcpt-to /password-reset@customer.com/ recipient-priority=100  
rcpt-to /special@customer.com/ virtual-mta=high, recipient-priority=60  
mail-from /newsletter/ recipient-priority=25  
</pattern-list>  
In the above example, individual emails to password-reset@customer.com will get the  
highest priority, generic emails to special@customer.com will get a slightly higher than  
normal priority, and any emails from anything containing newsletter will get a low  
priority.  
If both queue-priority and recipient-priority are used, queue-priority takes precedence.  
recipient-priority is only used for determining which recipients in a queue a retried first.  
260  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
10.9 SNMP Support  
10.9.1 Overview  
PowerMTA now supports SNMP for monitoring basic status information.  
Currently all the same information from the pmta show status command is what is  
vailable for monitoring via SNMP. This may be expanded over time to include additional  
information.  
PowerMTA SNMP support is included with the Windows installer and the Solaris  
package. There is a separate package available for Linux from the PowerMTA download  
page. PowerMTA's SNMP daemon can be used in master mode or as an AgentX  
subagent (not available on Windows). It automatically detects whether there is a AgentX  
master running (e.g. Net-SNMP's snmpd). If so it registers itself as a subagent, otherwise  
it runs in master mode.  
As a note, to allow Net-SNMP's snmpd to act as a AgentX master it is required to  
activate the AgentX support in snmpd (by having a line "master agentx" in snmpd.conf).  
The default configuration for PowerMTA's SNMP daemon is located in:  
Linux:  
/etc/pmta/pmtasnmpd.conf  
Windows:  
<PowerMTA directory>\pmtasnmp.conf  
Solaris:  
/etc/pmta/pmtasnmpd.conf  
This will allow anybody to read data from it with the "public" community string, which  
may or may not be appropriate. Since the SNMP daemon is based on Net-SNMP the  
configuration file is a standard Net-SNMP configuration file and documentation is  
available from:  
http://www.net-snmp.org/docs  
The data available through SNMP is described by the MIB which can be found at the  
following location:  
Linux:  
/usr/share/snmp/mibs/PowerMTA-MIB.txt  
Windows:  
<PowerMTA directory>\mibs\PowerMTA-MIB.txt  
Solaris:  
/etc/sma/snmp/mibs/PowerMTA-MIB.txt  
261  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
To access the data via SNMP a third party solution is required.  
On Linux or Solaris is you have the Net-SNMP utils installed you can test that it works  
(and see the data available) with the following command:  
snmpwalk -v2c -c public localhost PowerMTA-MIB::mta  
11. The Accounting and Statistics  
11.1 Introduction  
The accounting file maintains its ability to be written in the previously used binary  
format, but can now also be written in a CSV format or streamed to pipe. Some of the  
combinations (but not all) include:  
CSV format only  
Streamed to pipe only  
Binary format only  
Both CSV and pipe format  
Both CSV and binary format  
The last option is available for those organizations who want to continue to use their  
current setup while testing the new features for a future migration to this format.  
11.2 The Accounting File  
For efficiency and ease of use, PowerMTA writes accounting information to a separate  
file rather than to its logging file. Accounting is enabled in the initial configuration, so  
unless you disabled it you should find the accounting file(s) in the same directory as the  
logging file(s).  
Since PowerMTA will write detailed information to the accounting file for each message  
and report delivered, it will also increase overhead and such could impact throughput  
performance with larger workloads. If the accounting file is of no interest, you can  
disable it in the configuration file, however please note that the information included in  
the accounting file for each message is not readily available any where else in the  
solution.  
For ease of use, the accounting file is a CSV (Comma Separated Value) file. The old  
(binary) format is now deprecated, but will continue to be supported for at least one  
further major release of PowerMTA.  
There are 8 types of records available:  
262  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
Successful delivered records which provide the data for all messages successfully  
transferred to the destination domain mail servers.  
Bounced records which provide the data for all reports PowerMTA generated and  
delivered, including bounces for messages that PowerMTA could not deliver.  
Transient error & transient queue error records which show each unsuccessful  
delivery attempt of an individual message. These errors can be both for individual  
messages, or queue wide.  
Inbound recipients records which show each successful submission of an  
individual message to PowerMTA.  
Feedback loop records can be logged if PowerMTA has been configured with a  
<feedback-loop-processor>  
Remote bounce records can be logged if PowerMTA has been configured with a  
<bounce-processor>  
Remote Status records can be logged if PowerMTA has been configured with a  
<bounce-processor>  
Note that the "bounced" records may not include records for all bounces because  
messages routed through intermediary, relaying mailers may still bounce on their way to  
the final destination. These remote bounces (i.e. asynchronous bounces sent back by  
other mail servers) are recorded as successful transfers since they were successfully  
transferred initially, and at that point are completely out of the control of PowerMTA.  
All records are written to the accounting file at the time the message or report is  
delivered, so they will be ordered by delivery time.  
11.2.1 Accounting records  
PowerMTA writes an accounting record per recipient delivered. These various records  
can be stored in all in one file, or in separate files by record type. The CSV field typeis  
used to determine one of four possible values for the file. The various types are “d” for  
delivered, “b” for bounced, or “t” for transient, “tq” for transient-queue, and “r” for  
received. By default, only “d” and “b” records are recorded.  
11.2.2 "Successful delivered" Records  
The following are all the default fields for the CSV file when using “d” or “delivery” as  
the recordtype.  
CSV  
Binary  
Description  
Accounting Accounting  
File  
File  
(record- (Previous  
fields) versions)  
type  
n/a  
Type of record (“d” or “delivery”)  
263  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
timeLogged  
t
Time the record was delivered and  
logged to the accounting file  
timeQueued  
orig  
tq  
Time message was queued to disk  
originator (from MAIL FROM:<x>)  
recipient (RCPT TO:<x>) being reported  
orig  
r
rcpt  
orcpt  
or  
original recipient (from RCPT TO:...  
ORCPT=x), immediately following the  
recipient to which it refers  
dsnAction  
dsnStatus  
dsnDiag  
dsnMta  
dsnAct  
DSN action for the recipient to which it  
refers  
dsnSts  
DSN status for the recipient to which it  
refers  
dsnDiag  
dsnMTA  
DSN diagnostic string for the recipient to  
which it refers  
DSN remote MTA for the recipient to  
which it refers  
srcType  
srcMta  
src.type  
src.mta  
source type from which the message was  
received, either 'api' or 'smtp'  
source from which the message was  
received. the MTA name (from the  
HELO/EHLO command) for messages  
received through SMTP  
dlvType  
dlvThrough  
dlvFrom  
delivery method, one of “smtp”, “pipe”,  
“discard”, or “file”  
dlvSourceIp  
local IP address PowerMTA used for  
delivery  
dlvDestinationIp dlvTo  
dlvEsmtpAvailable esmtp  
IP address of the mailer to which the  
report/message was delivered  
SMTP extensions supported by receiving  
mailer  
dlvSize  
vmta  
size  
vmta  
report/message size in bytes  
VirtualMTA selected for this message, if  
any  
jobId  
envId  
jobId  
envId  
job ID for the message, if any  
envelope Id, from MAIL FROM:...  
ENVID=x(present only if specified)  
264  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
header_XXX  
userString  
header.name +  
header.content  
for each custom header included where  
XXX is the name of the header, if any  
n/a  
String added to accounting file as defined  
by the <acct-file> directive user-string.  
Sample accounting entry for a delivery record:  
d,1191435989,1191435961,,,testfrom@port25.com,testto@port25.com,,relayed,2.0.0  
(success),, [192.168.0.10]  
(192.168.0.10),success,api,,smtp,10.25.25.211,10.25.25.20,,316,vmta0,0,0  
11.2.3 “Bounced” Records  
The following are all the default fields for the CSV file when using “b” or “bounced“ as  
the recordtype.  
CSV  
Binary Description  
Accounting Accounting  
File  
File  
(record-  
fields)  
type  
(Previous  
versions)  
b
Type of record (“b” or “bounce”)  
timeLogged  
t
Time the record was delivered and logged  
to the accounting file  
timeQueued  
orig  
tq  
Time message was queued to disk  
originator (from MAIL FROM:<x>)  
recipient (RCPT TO:<x>) being reported  
orig  
r
rcpt  
orcpt  
or  
original recipient (from RCPT TO:...  
ORCPT=x), immediately following the  
recipient to which it refers  
dsnAction  
dsnStatus  
dsnDiag  
dsnAct  
dsnSts  
dsnDiag  
dsnMTA  
DSN action for the recipient to which it  
refers  
DSN status for the recipient to which it  
refers  
DSN diagnostic string for the recipient to  
which it refers  
dsnMta  
DSN remote MTA for the recipient to  
which it refers  
265  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
bounceCat  
srcType  
bncCat  
likely category of the bounce (see Section  
1.5), following the recipient which it  
refers  
src.type  
source type from which the message was  
received, either 'api' or 'smtp'  
srcMta  
src.mta  
dlvThrough  
dlvFrom  
dlvTo  
No data present in Bounce Record  
No data present in Bounce Record  
No data present in Bounce Record  
No data present in Bounce Record  
No data present in Bounce Record  
No data present in Bounce Record  
dlvType  
dlvSourceIp  
dlvDestinationIp  
dlvEsmtpAvailable  
dlvSize  
esmtp  
size  
vmta  
vmta  
VirtualMTA selected for this message, if  
any  
jobId  
envId  
jobId  
envId  
job ID for the message, if any  
envelope Id, from MAIL FROM:...  
ENVID=x(present only if specified)  
header_XXX  
userString  
header.name +  
header.content  
for each custom header included where  
XXX is the name of the header, if any  
n/a  
String added to accounting file as defined  
by the <acct-file> directive user-string.  
Sample accounting entry for a bounce record:  
b,1191424958,1191424481,,,testfrom@port25.com,testto@port25.com,,failed,4.4.1 (no answer  
from host),,[192.168.0.10] (192.168.0.10),no-answer-from-host,api,,,,,,,vmta0,0,0  
11.2.4 “Transient error” Records  
There are times when sending emails may fail. To help identify these issues, PowerMTA  
has the ability to show transient errors per message. This logging is handled with the  
record type “t”. The fields available are as follows:  
266  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
CSV  
Binary Description  
Accounting Accounting  
File  
File  
(record-  
fields)  
type  
(Previous  
versions)  
n/a  
Type of record (“t” or “transient”)  
timeLogged  
t
Time the record was delivered and logged  
to the accounting file  
timeQueued  
orig  
tq  
Time message was queued to disk  
originator (from MAIL FROM:<x>)  
recipient (RCPT TO:<x>) being reported  
orig  
r
rcpt  
orcpt  
or  
original recipient (from RCPT TO:...  
ORCPT=x), immediately following the  
recipient to which it refers  
dsnAction  
dsnStatus  
dsnDiag  
dsnAct  
dsnSts  
dsnDiag  
dsnMTA  
bncCat  
DSN action for the recipient to which it  
refers  
DSN status for the recipient to which it  
refers  
DSN diagnostic string for the recipient to  
which it refers  
dsnMta  
DSN remote MTA for the recipient to  
which it refers  
bounceCat  
likely category of the bounce (see Section  
1.5), following the recipient which it  
refers  
srcType  
srcMta  
src.type  
src.mta  
source type from which the message was  
received, either 'api' or 'smtp'  
source from which the message was  
received. the MTA name (from the  
HELO/EHLO command) for messages  
received through SMTP  
dlvType  
dlvThrough  
dlvFrom  
delivery method, one of “smtp”, “pipe”,  
“discard”, or “file”  
dlvSourceIp  
local IP address PowerMTA used for  
delivery  
267  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
dlvDestinationIp  
dlvEsmtpAvailable  
dlvTo  
esmtp  
IP address of the mailer to which the  
report/message was delivered  
SMTP extensions supported by receiving  
mailer  
dlvSize  
vmta  
size  
vmta  
report/message size in bytes  
VirtualMTA selected for this message, if  
any  
jobId  
envId  
jobId  
envId  
job ID for the message, if any  
envelope Id, from MAIL FROM:...  
ENVID=x(present only if specified)  
header_XXX  
userString  
header.name +  
header.content  
for each custom header included where  
XXX is the name of the header, if any  
n/a  
String added to accounting file as defined  
by the <acct-file> directive user-string.  
Sample accounting entry for a transient record:  
t,1188490693,1188481072,,,support@port25.com,test@port25.com,,failed,  
4.0.0 (undefined status),mailbox unavailable,,  
other,api,,,,,,,vmta0,6,0  
Note: Since many sites use the same originator address for all messages across all  
campaigns and mailings, the JobID, if included in your messages fed to PowerMTA, can  
be used to track specific mailings on a per campaign or per message basis since it is a  
field that can be included in each accounting record.  
The format in the SMTP envelope in your original message is simply:  
MAIL FROM:<bounceaddress@yourdomain.com> ENVID=yourenvId  
with additional details (such as a limit of 100 characters for ENVID) found in RFC 1891.  
11.2.5 “Transient Queue” Records  
There are times when sending emails that an entire given queue may fail. It may be  
problems with a particular outbound IP address, or maybe one domain is currently  
offline. To help identify these issues, PowerMTA has not only the ability to show  
transient recipient errors per message, but also the same information on a per queue basis.  
This logging is handled with the record type “tq”. The records when using “tq” are  
slightly different than those mentioned above. The fields available are as follows:  
268  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
CSV  
Binary  
Description  
Accounting Accounting  
File  
File  
(record- (Previous  
fields) versions)  
type  
n/a  
Type of record (“tq” or “transient  
queue”)  
current time  
queue name  
VirtualMTA name  
timeLogged  
queue  
t
tq  
vmta  
vmta  
dsnStatus  
dsnDiag  
dsnMta  
dsnSts  
dsnDiag  
dsnMta  
dlvThrough  
dlvFrom  
DSN status code for failure  
DSN diagnostic string for failure  
remote MTA, if applicable  
delivery type  
IP address from which the  
connection was made/attempted  
IP address to which the connection  
as made/attempted  
dlvType  
dlvSourceIp  
dlvDestinationIp dlvTo  
userString  
n/a  
String added to accounting file as  
defined by the <acct-file> directive  
user-string.  
Sample accounting entry for a transient queue record:  
tq,1191436554,port25.com/vmta0,,vmta0,4.4.1 (no answer from  
host),port0.com,[192.168.0.10] (192.168.0.10),smtp,192.168.0.11,192.168.0.10  
If the record type “tq” is used for the same CSV file as “d”, “b”, or “t” all fields from  
both tables will be included, possibly resulting in many empty data fields.  
11.2.6 “Received” Records  
PowerMTA can log messages in the accounting file during the injection process. This  
logging is handled with the record type “r”. The records when using “r” are slightly  
different than those mentioned above. The fields available are as follows:  
CSV  
Binary  
Description  
Accounting Accounting  
File  
File  
(record- (Previous  
fields) versions)  
269  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
type  
n/a  
n/a  
n/a  
n/a  
Type of record (“r” or “received”)  
current time  
originator (from MAIL FROM:<x>)  
recipient (RCPT TO:<x>) being  
reported  
original recipient (from RCPT  
TO:... ORCPT=x), immediately  
following the recipient to which it  
refers  
timeLogged  
orig  
rcpt  
orcpt  
n/a  
srcType  
srcMta  
n/a  
n/a  
source type from which the message  
was received, either 'api' or 'smtp'  
source from which the message was  
received. the MTA name (from the  
HELO/EHLO command) for  
messages received through SMTP  
IP address of the server connecting  
to PowerMTA  
IP address PowerMTA used to  
handle the connection  
VirtualMTA selected for this  
message, if any  
job ID for the message, if any  
envelope Id, from MAIL FROM:...  
ENVID=x(present only if specified)  
for each custom header included  
where XXX is the name of the  
header, if any  
String added to accounting file as  
defined by the <acct-file> directive  
user-string.  
rcvSourceIp  
n/a  
rcvDestinationIp n/a  
vmta  
n/a  
jobid  
envid  
n/a  
n/a  
header_XXX  
userString  
n/a  
n/a  
Sample accounting entry for a received record:  
r,2010-04-17 16:19:57-0400,test@port25.com,test@port25.com,,smtp,tesFeeder  
(192.168.25.56),192.168.25.56,192.168.25.11,vmta1,job2,envid1234  
If the record type “r” is used for the same CSV file as “d”, “b”, or “t” all fields from both  
tables will be included, possibly resulting in many empty data fields.  
270  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
11.2.7 “Remote Bounce” & “Remote Status”  
Records  
PowerMTA can log remote (asynchrouns) bounces in the accounting file and remote  
status reports. This logging is handled with the record type “rb” for remote bounce and  
"rs" for reporting other kinds of remote status (used for DSN positive and "delayed"  
status notifications). The records when using “rb” or “rs” are slightly different than those  
mentioned above. The fields available are as follows:  
CSV  
Binary  
Description  
Accounting Accounting  
File  
File  
(record- (Previous  
fields) versions)  
type  
n/a  
n/a  
n/a  
n/a  
n/a  
Type of record “rb” or “rs”  
current time  
timeLogged  
orig  
originator address (of original email)  
recipient address (of original email)  
original recipient (from RCPT  
TO:... ORCPT=x), immediately  
following the recipient to which it  
refers  
rcpt  
orcpt  
dsnAction  
dsnStatus  
dsnDiag  
n/a  
n/a  
n/a  
n/a  
DSN action  
DSN status  
DSN diagnostic  
DSN remote MTA  
DSN reporting MTA  
bounce category  
dsnMta  
dsnReportingMta n/a  
bounceCat  
srcType  
n/a  
n/a  
source type from which the message  
was received, either 'api' or 'smtp'  
source from which the message was  
received. the MTA name (from the  
HELO/EHLO command) for  
messages received through SMTP  
envelope Id, from MAIL FROM:...  
ENVID=x(present only if specified)  
header extracted from original email  
srcMta  
n/a  
envid  
n/a  
n/a  
header_<name>  
Sample accounting entry for a received record:  
rb,2010-12-01 14:24:44-0500,bounce@bounce.com,lksjflkj@somedomain.com,,5.1.1 (bad destination  
mailbox address),"smtp;550 5.1.1 no such local recipient: <lksjflkj@somedomain.com> in ""RCPT  
TO:<lksjflkj@somedomain.com>""",mail.remotedomain.com (169.3.169.30),my.local.server.com,bad-  
271  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
mailbox,smtp,my.local.server.com (192.168.0.150),  
If the record type “rb” or “rs” is used for the same CSV file as “d”, “b”, or “t” all fields  
from both tables will be included, possibly resulting in many empty data fields.  
11.2.8 “Feedback Loop” Records  
PowerMTA can log feedback loop reports in the accounting file. This logging is handled  
with the record type “f”. The records when using “f” are slightly different than those  
mentioned above. The fields available are as follows:  
CSV  
Binary  
Description  
Accounting Accounting  
File  
(record-  
File  
(Previous  
fields)  
versions)  
type  
n/a  
n/a  
n/a  
Type of record “f”  
Current time  
the IP of PowerMTA that received  
the message  
"arf" or "jmrp"  
timeLogged  
rcvSourceIp  
format  
n/a  
n/a  
userAgent  
name & version of the program that  
generated the report  
envid  
n/a  
n/a  
n/a  
n/a  
envelope ID (of original email)  
originator address (of original email)  
recipient address (of original email)  
the name of the MTA generating this  
feedback report  
orig  
rcpt  
reportingMTA  
sourceIp  
n/a  
address of MTA from which the  
message was received  
header_From  
n/a  
n/a  
n/a  
n/a  
n/a  
n/a  
n/a  
from header (of original email)  
return-path header (of original email)  
x-job header (of original email)  
Subject header (of original email)  
header extracted from original email  
field from ARF feedback-report  
the domain about which the feedback  
report was generated  
header_Return-Path  
header_X-job  
header_Subject  
header_<name>  
arf_<name>  
reportedDomain  
Sample accounting entry for a received record:  
f,2010-04-12 11:40:37-0400,arf,AOL SComp,,,,mail1.domain.com,169.63.151.30  
272  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
If the record type “f” is used for the same CSV file as “d”, “b”, or “t” all fields from both  
tables will be included, possibly resulting in many empty data fields.  
11.2.9 Encoding  
As much as possible, standard CSV encodings are used for all fields, with most  
characters being as-is in the output. Time stamps are normally formatted as UNIX  
time_t, i.e., the number of seconds since midnight on January 1, 1970.  
The format of the file is CSV (comma-separated values), as described in RFC 4180, with  
a header line at the beginning of the file describing what field is in which column. Here  
is the format from RFC 4180 in short: columns are separated by commas and records  
terminated with CRLF. Values may be quoted with double quotes (""), and must be  
quoted if its value contains a comma, a double quote or CRLF. A double quote occurring  
within double quotes is repeated, like in:  
two inches,"2"""  
To accommodate writing various record types in the same file, the first column is always  
the record type. If an accounting file is configured (or defaulted) to have multiple record  
types, all the possible columns from the selected records are included. For example, if a  
file was configured as:  
records d, b  
record-fields delivery timeLogged,orig,rcpt,dlvSourceIp  
record-fields bounce timeLogged,orig,rcpt,bounceCat  
the resulting file (including a few record of each type) might look like:  
type,timeLogged,orig,rcpt,dlvSourceIp,bounceCat  
d,1178807903,orig@port25.com,user1@domain.com,10.0.0.1,  
d,1178807905,orig@port25.com,user2@domain.com,10.0.0.1,  
b,1178807915,orig@port25.com,user3@domain.com,,policy-related  
b,1178807915,orig@port25.com,user4@domain.com,,policy-related  
Note that the dlvSourceIp field was omitted (empty field at the end) for the 'b' record, and  
that the bounceCat was omitted in the 'd' record, because they were not configured.  
11.3 Configuring the accounting file  
When installing PowerMTA over a previous version that used the previous binary format  
of the accounting file, the binary format will remain in place. To use the CSV format  
after an upgrade like this, PowerMTA will need to be properly configured. All new  
installs in which a previous version of PowerMTA is not present will use the CSV  
format.  
273  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
Use of the new accounting file format requires the <acct-file>tag. The tag takes one  
or more parameters. If passing one parameter, it can specify the location of the CSV file.  
If passing more than one, it can specify the location of the executable program to which  
PowerMTA should pipe the accounting records. If using pipe, the first parameter will  
need to be preceded by a “|”. It may be required to quote the acct file path if it contains  
spaces (like <acct-file "c:\my stuff\acctproc.exe">) or if arguments are passed (like <acct-  
file "/bin/foo.pl -x -a -z">) Examples are listed in the section 1.3.2.  
In the current pipe implementation, if PowerMTA runs into a problem writing to the pipe,  
it gives up on it and won't retry either until the next "pmta reload" command is run, or  
after a certain predefined time limit. With this, it will be necessary for customers to  
configure PowerMTA to create a corresponding accounting data file as well, in order to  
have the data to recover, if there are problems with the customer's pipe application.  
In the event of a broken pipe, PowerMTA writes:  
Error TYPE "CMD": DETAILS  
to the logging file, where TYPE is one of "starting", "writing to" or "executing", CMD is  
the configured command, and DETAILS is a string with details on what went wrong.  
Each time a pipe is started, the first line written to it is a headers line with the various  
fields (like in the CSV files). It is only re-started upon a "pmta reload".  
11.3.1 Directives  
The User’s Guide covers the various directives that can be used with <acct-file>, but  
they are included here for your convenience.  
delete-after  
Scope:  
Type:  
acct-file  
{#d|never}  
Attributes: optional  
Default:  
8d (8 days)  
This directive tells PowerMTA how long to keep the accounting file before  
deleting it from the server. "delete-after" only applies if "move-to" isn't active"  
(and move-to must point to a different location than the directory where the file  
was originally created).  
274  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
move-to  
Scope:  
Type:  
acct-file  
directory  
Attributes: optional  
Default:  
files not moved  
This directive tells PowerMTA where to move the accounting file when using  
move-interval or max-size. Directory must be on the same volume as the  
accounting files. Moving across a network is not supported.  
move-interval  
Scope:  
Type:  
acct-file  
time interval  
Attributes: optional  
Default:  
1d  
This directive tells PowerMTA at what time interval to move the accounting file  
and start a new one.  
max-size  
Scope:  
Type:  
acct-file  
{n{B|K|M|G|T}|unlimited}  
Attributes: optional  
Default:  
250M  
The max size of the accounting file in Bytes, Kilobytes, Megabytes, Gigabytes, or  
Terabytes before PowerMTA moves the accounting file and starts a new one.  
Minimum size is 1M (1000000B & 1000K) & Maximum size is 1T. This  
directive applies both with and without "move-to". If "move-to" is not specified,  
a new file is started in place (with a higher –NNNN in the file name).  
retry-interval  
Scope:  
Type:  
acct-file  
time interval  
Attributes: optional  
Default:  
5m  
Retries the pipe program in a regular interval in case of a failure. This should  
only be used when using pipe to write an accounting file.  
275  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
user-string  
Scope:  
acct-file  
string  
Type:  
Attributes: optional  
Default:  
Specifies a custom string to be stored along with other MTA information in  
theaccounting file.  
write-timeout  
Scope:  
Type:  
acct-file  
time interval  
Attributes: optional  
Default:  
1m  
Allows for setting write timeouts in accounting pipes, so that an unresponsive  
accounting application doesn't hold up PowerMTA indefinitely. Only used when  
pipeing accounting data to another file.  
276  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
records  
Scope:  
Type:  
acct-file  
one or more comma-separated record types  
Attributes: optional  
Default:  
d,b  
This directive tells PowerMTA which record types to include in the accounting  
file. There are 8 record types: d, b, t, tq, r, f, rb, & rs.  
“d” is for delivered records and will include all messages that were  
successfully delivered. “delivery” can be used in place of “d”.  
“b” is for bounced records and will include all locally generated bounces  
(synchronous bounces). Note that bounces generated by remote mail servers  
(asynchronous bounces) will not be included. “bounce” can be used in place  
of “b”.  
“t” is for transient recipient level errors only (such as mailbox full).  
“transient” can be used in place of “t”.  
“tq” is for queue wide transient errors and will include information about  
delivery attempts for a given domain/vmta. “transient-queue” can be used  
in place of “t”.  
“r” is for inbound records and will include information about messages  
submitted to PowerMTA for delivery. “receipt” can be used in place of “r”.  
“f” is for feedback loop emails if PowerMTA is configured to look for  
feedback loop emails with the <feedback-loop-processor>. “feedback-loop”  
may be used in place of “f”. See Section 12.7 for more information.  
“rb” is for remote bounce emails if PowerMTA is configured to look for  
remote bounce emails with the <bounce-processor>. “remote-bounce” may  
be used in place of “rb”. See Section 12.6 for more information.  
“rs” is for remote status emails if PowerMTA is configured to look for remote  
status emails with the <bounce-processor>. “remote-status” may be used in  
place of “rs”. See Section 12.6 for more information.  
Due to the fact that there can be many delivery attempts for one message, it is  
suggested that type “t” and/or “tq” should only be used when needed (debugging,  
troubleshooting, etc.) as it may cause large file sizes. It is also recommended  
when using this setting to have the “t” or “tq” type records written to their own  
file, as so not to cause unwanted data in the primary accounting file.  
277  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
record-fields  
Scope:  
acct-file  
Type:  
record type followed by a comma-separated list of field names  
Attributes: optional  
Default:  
*
This directive specifies the fields to be included in the accounting file. By default  
all are included. To include only a subset of all the fields, simply add the desired  
fields in a comma separated list. To include a custom header, add the record field  
header_XXX, where XXX is the name of the custom field you wish to log. For  
example, to log all fields and a custom header, the directive would look like this:  
record-fields delivery *,header_Message-Id  
To include only a subset of the fields, list the required fields similar to the  
following:  
record-fields bounce timeLogged,orig,rcpt,dlvSourceIp,vmta  
To exclude fields from the default, you can use an “!” to exclude the unwanted  
fields. For example, to include all fields except orcpt you would use:  
record-fields d *,!orcpt  
record-fields b *,!orcpt  
world-readable  
Scope:  
Type:  
acct-file  
boolean  
Attributes: optional  
Default:  
no  
This directive tells PowerMTA what read permissions to set on the accounting  
file.  
count-moved-records  
Scope:  
acct-file  
Type:  
boolean  
Attributes: optional  
Default:  
false  
This directive tells PowerMTA whether or not to count the records in CSV files  
moved. The record counts are written to the logging file along with the message  
that indicates that the file was moved.  
278  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
sync  
Scope:  
Type:  
acct-file  
boolean  
Attributes: optional  
Default:  
no  
Determines whether the OS' buffers for the accounting file are flushed regularly.  
This helps ensure that the accounting data isn't corrupted in case of a system  
crash.  
11.3.2 Examples  
The accounting file is configured with the <acct-file> type directive with the date added  
as part of the file name. For example <acct-file log/acct.csv> yields a file name like  
/pmta/log/acct-2007-09-05-0000.csv. By default on a new installation, the settings will  
look similar to the following:  
<acct-file log\acct.csv>  
# move-to c:\myapp\pmta-acct # configure as fit for your application  
move-interval 1d  
max-size 250M # MB  
</acct-file>  
The data may also be written to pipe. This can be useful if a custom application is  
created in which the data would be written to a database in real time. PowerMTA  
instantiates the script only once at startup and then keeps passing data to the pipe as and  
when available. An example would look similar to the following:  
<acct-file |C:\pmta\bin\customCode.exe -–thisOption --thatOption>  
</acct-file>  
Multiple files can be used if needed. For example, it may be more convenient to have all  
bounces and deliveries in one file and transient reports in another file. An example of  
such would be similar to the following:  
<acct-file log\acct-bd.csv>  
records b,d  
record-fields d *,!orcpt,header_myCustomHeader  
record-fields b *,!orcpt  
</acct-file>  
<acct-file log\acct-t.csv>  
records t,tq  
</acct-file>  
279  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
In addition to the examples above, both the CSV file and older binary file can be created  
by PowerMTA at the same time. This may be useful for organizations that want to  
migrate from one to the other without having to use a separate server to generate data  
with which to test. Please note that the binary format uses a global directive, whereas the  
CSV format uses a tag similar to a domain or source tag. The configuration for this  
would look similar to the following:  
# Binary format  
acct-file log\old-acct.dat  
# CSV format  
<acct-file log\acct.csv>  
move-to c:\myapp\pmta-acct # configure as fit for your application  
move-interval 1d  
max-size 250M # MB  
</acct-file>  
Using both types of accounting files at the same time will increase HDD I/O and may  
result in degraded performance.  
11.4 The pmtastats Accounting Statistics Application  
PowerMTA comes with an accounting file parsing application, pmtastats, that  
calculates delivery throughput and general traffic statistics both on a global basis and/or  
on a per campaign or mailing basis.  
This application was historically known as  
"acctstats" but renamed to "pmtastats" starting in v3.5, given the enhanced functionality  
added to this application. If you want to generate the historical "acctstats" output with  
"pmtastats", simply use the "--acctstats" flag when running the application. For example:  
pmtastats --acctstats acct.csv  
You can use pmtastats with either binary or CSV-encoded accounting files: it  
automatically detects the file format and processes it accordingly.  
If you wish to run the parsing application over more than one accounting file (for  
example, if the accounting file was rotated while sending a campaign), simply specify the  
various files within the same command. For example:  
pmtastats [global options] [statistic [options] ..] acct.dat acct-1.dat  
11.4.1 pmtastats Options  
pmtastatshas the following options, as shown by the --helpoutput:  
PowerMTA(TM) v3.3 statistics program  
Copyright(c) 1999-2007, Port25 Solutions, Inc. All Rights Reserved.  
Usage: pmtastats [global options] [statistic [options] ...] file ...  
280  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
One or more statistics can be specified, each with its own options. Use with  
one or more files, in either binary, CSV or XML format. '-' can be used for  
reading from standard input.  
examples:  
pmtastats vmta-summary vmta-time-breakdown acct*.*  
pmtastats bounce-categories --bounceCat all acct*.*  
pmtastats --vmta vmta1 top-rates delivery-times acct*.*  
pmtastats --output html vmta-time-breakdown acct*.* > report.html  
global options:  
--help  
display this help and exit  
--version  
display version information and exit  
--quiet  
do not display progress information  
--output <format>  
selects the output format (text, html; default: text)  
--envId <id>  
--from <originator>  
--toDomain <domain>  
--jobId <id>  
--vmta <vmta>  
--header <name> <content>  
filter input: use only records whose envelope ID, originator,  
recipient domain, job ID, VirtualMTA, or the given header  
starts with the given string, respectively  
(default: no filtering)  
--last DdHhMmSs  
filter input: use only records written in the last D days, H hours,  
M minutes and S seconds. Each part of the time specification can  
be omitted, such as in "3h15m" for 3 hours, 15 minutes.  
(default: no filtering)  
--byEnvId  
--byJobId  
--byFrom  
--byVmta  
--byHeader <header>  
statistics split by envelope ID, job ID, originator, VirtualMTA, or a  
given header, respectively.  
Only one of these can be used.  
For --byHeader, specify the header.  
(default: statistics not split)  
--splitLimit <num>  
set the maximum number of statistics a statistic can be split into  
(default: 5000)  
--topDomains <num>  
display top <num> domains (passed on to all statistics)  
"bounce-categories" statistic  
Shows most frequent bounce categories.  
Options:  
--topCategories <num>  
display top <num> bounce categories (default: 10)  
--bounceCat <option>  
selects categories for detailed display. Possible options are:  
<num> - top <num> categories  
<category> - category name  
'all' - all available categories  
(default: spam-related)  
--byDsn <num>  
display bounce category detail for the top <num> DSN codes (default: 10)  
--byDomain <num>  
display bounce category detail for the top <num> domains (default: 10)  
--byDsnAndDomain <num>  
281  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
display bounce category detail for the top <num> DSN code / domain  
combinations (default: 10)  
"delivery-times" statistic  
Shows times and recipients / time from queueing to delivery.  
Options:  
(none)  
"just-delivery-times" statistic  
Time just for delivery.  
Options:  
(none)  
"message-counts" statistic  
Total counts of recipents and volume for messages and bounces.  
Options:  
(none)  
"top-bounce" statistic  
Top bounce domains, aggregated by DSN code (reason).  
Options:  
--topDomains <num>  
display bounce statistic for top <num> domains (default: 10)  
--topStatusCodes <num>  
display bounce statistics for top <num> status codes (default: 10)  
"top-domains" statistic  
Domains with the most recipients, bounces, and delivery times.  
Options:  
--topDomains <num>  
display top <num> domains (default: 10)  
--noDeliveryTimes  
omits list of domains with the highest average delivery times  
(default: includes it)  
"top-rates" statistic  
Data transfer and recipient rates over time.  
Options:  
(none)  
"vmta-summary" statistic  
High-level VirtualMTA traffic summary.  
Options:  
--byDate  
split records by date (default: no splitting done)  
"vmta-time-breakdown" statistic  
Dailiy and hourly recipients and bounces for each VirtualMTA.  
Options:  
--noHourly  
do not include hourly breakdown (default: include it)  
"vmta-top-bounce" statistic  
Bounces for individual VirtualMTAs.  
Options:  
--topBounced <num>  
show top <num> domains by bounces (default: 20)  
--byDate  
split records by date (default: no splitting done)  
shortcut options:  
--all  
create all available statistics with default options  
--acctstats  
create statistics similar to what acctstats did  
282  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Note: On Windows NT/2000, you can also use the "/" character instead of "--" (but "--"  
works on all platforms).  
The following is a list of the various fields available, and which reports return those  
fields.  
bounceCat  
dlvSourceIp  
dsnDiag  
dsnStatus  
envId  
*
*
*
*
*
*
*
*
*
*
*
*
header_<xyz>  
jobId  
nRcpt  
*
*
*
*
*
*
*
*
*
*
*
orig  
rcpt  
*
*
*
size  
*
*
timeLogged  
timeQueued  
vmta  
*
*
*
*
*
*
*
*
*
11.4.2 pmtastats Report Breakdown  
Given the various reports available, different data will or will not be included in each  
report based on the options used. Here is a sample of the reports available and their  
output. Multiple reports can be run at the same time.  
283  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
11.4.2.1 Time Frame  
Time Frame:  
first  
last  
------------------- -------------------  
2007-01-15 14:19:11 2007-01-17 00:42:01  
received  
delivered/bounced 2007-01-16 03:30:45 2007-01-17 03:15:46  
This section is always generated for each report type, and shows the first and the last  
receipt time stamps and the first and the last delivery time stamps of the applicable  
messages. The scope of the output is based on the type of report specified, i.e., global or  
by originator or by envelope ID, and such can be used to calculate a campaign duration  
time. In this example, the mailing duration would be 13 hours 56 minutes and 35 seconds,  
which is the difference between when the first message was received (2007-01-15  
14:19:11) and the last message was delivered (2007-01-17 03:15:46).  
11.4.2.2 Bounce Categories  
Total Bounce Breakdown By Category:  
Bounce reports (across 14 categories):  
total bounced 5.X.X bounces 4.X.X bounces  
------------- ------------- -------------  
94,457  
89,678  
4,779  
bounced %bounced bounce category description  
------- -------- ------------------- -----------  
42,600  
27,175  
13,045  
3,528  
2,206  
2,104  
1,761  
877  
45.1% other  
messages rejected due to other reasons, 4.X.X or 5.X.X error  
messages refused or blocked due to spam related reasons, 5.X.X error  
messages rejected due to bad, invalid, or non-existent recipient addresses, 5.X.X error  
messages rejected due to expired, inactive, or disabled recipient addresses, 5.X.X error  
28.8% spam-related  
13.8% bad-mailbox  
3.7% inactive-mailbox  
2.3% no-answer-from-host messages bounces due to receiving no response from remote host after connecting, 4.X.X or 5.X.X error  
2.2% policy-related  
1.9% message-expired  
0.9% routing-errors  
0.8% bad-domain  
messages refused or blocked due to general policy reasons, 5.X.X error  
messages bounced due to not being delivered before the bounce-after, 4.X.X error  
messages bounced due to mail routing issues for recipient domain, 5.X.X error  
messages bounced due to invalid or non-existing domains, 5.X.X error  
messages rejected due to mailbox quota issues, 4.X.X or 5.X.X error  
715  
228  
0.2% quota-issues  
This report list the top level bounce information. The scope of the output is based on the  
type of report specified, and the above example is done using no additional options.  
Note that the report is based only on the messages that have already been handled by  
PowerMTA. If the report is generated while PowerMTA is still attempting to deliver  
some of the messages, these will not be included in the report.  
11.4.2.3 Delivery Times  
Delivery Times And Numbers (total queue time):  
Delivery times per percentage of recipients (successful deliveries only):  
recipients avg. time max. time %rcpt.  
---------- --------- --------- ------  
1,601,910  
1,922,292  
2,242,674  
2,563,056  
2,883,438  
3,043,629  
3,075,667  
3,107,705  
3,139,743  
0:00:11  
0:00:19  
0:00:37  
0:01:15  
0:03:38  
0:09:17  
0:10:31  
0:11:50  
0:13:35  
0:00:39  
0:01:32  
0:03:34  
0:07:51  
1:30:09  
2:04:30  
2:12:13  
2:26:06  
3:27:07  
50%  
60%  
70%  
80%  
90%  
95%  
96%  
97%  
98%  
284  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
3,171,781  
3,203,820  
0:15:39  
0:18:33  
3:55:34  
16:11:17  
99%  
100%  
Deliveries per time increment (successful deliveries only):  
interval (between) histogram recipients  
%rcpt.  
------------------ ----------------------- ----------- ------  
0 - 5 seconds  
6 - 30 seconds  
31 - 60 seconds  
1 - 2 minutes  
2 - 5 minutes  
5 - 10 minutes  
10 - 30 minutes  
30 - 60 minutes  
1 - 2 hours  
2 - 3 hours  
3 - 4 hours  
4 - 5 hours  
5 - 6 hours  
6 - 8 hours  
8 - 10 hours  
10 - 12 hours  
after 12 hours  
***  
******  
**  
*
**  
**  
517,753  
952,742  
328,600  
223,472  
320,070  
350,851  
122,132  
35,897  
171,876  
97,408  
54,527  
18,589  
4,605  
16.2%  
29.7%  
10.3%  
7.0%  
10.0%  
11.0%  
3.8%  
1.1%  
5.4%  
3.0%  
1.7%  
0.6%  
0.1%  
0.1%  
0.0%  
0.0%  
0.0%  
*
3,560  
376  
1,016  
346  
Cumulative deliveries per time increment (successful deliveries only):  
interval histogram recipients  
----------------- ----------------------- ----------- ------  
%rcpt.  
within 5 seconds  
within 30 seconds **********  
***  
517,753  
1,470,495  
1,799,095  
2,022,567  
2,342,637  
2,693,488  
2,815,620  
2,851,517  
3,023,393  
3,120,801  
3,175,328  
3,193,917  
3,198,522  
3,202,082  
16.2%  
45.9%  
56.2%  
63.1%  
73.1%  
84.1%  
87.9%  
89.0%  
94.4%  
97.4%  
99.1%  
99.7%  
99.8%  
99.9%  
within 1 minute  
within 2 minutes  
within 5 minutes  
within 10 minutes *******************  
within 30 minutes ********************  
within 1 hour  
within 2 hours  
within 3 hours  
within 4 hours  
within 5 hours  
within 6 hours  
within 8 hours  
within 10 hours  
within 12 hours  
after 12 hours  
************  
**************  
****************  
********************  
*********************  
**********************  
**********************  
**********************  
**********************  
**********************  
***********************  
***********************  
***********************  
3,202,458 100.0%  
3,203,474 100.0%  
3,203,820 100.0%  
This section and respective outputs are always generated and the scope of the outputs are  
based on the type of report specified, i.e., global or by originator/envelope ID. They also  
are primarily based on the difference between each message's queue timestamp and  
transfer timestamp for only the messages that were successfully delivered by PowerMTA.  
As mentioned in Section 1.3.2.7, for the avg. time and max. time calculations, each  
recipient is counted by itself, even if a message is transferred in multi-recipient SMTP  
transactions.  
The avg. time is calculated by adding together the fastest n% transfer times (transfer  
timestamp - queue timestamp) and then dividing this sum by the number of recipients that  
make up n% of the total deliveries. For example, in the 80% fastest delivery line in the  
top output, one would read that it took an average of 21 seconds for each message to each  
recipient to be delivered once each was queued, for the fastest 80% of all transfer times  
(or to 7,504,928 recipients).  
285  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
The max. time is the longest transfer time (transfer timestamp - queue timestamp) for  
one message from all of the fastest transfer times for the number of recipients. In the 80%  
fastest delivery case, one would read that the longest it took for a message to be  
transferred, for the fastest 80% of all transfer times (or to 7,504,928 recipients), was 4  
minutes and 24 seconds. Conversely, all of the 80% messages were transferred in equal  
or less time. Note that this does not show total campaign duration time since these figures  
are only based on each message's own transfer time.  
It is important to see with this report the overall impact that slow or initially unreachable  
domains have on throughput efficiency, especially if it happens to be a domain with a  
large number of queued recipients.  
11.4.2.4 Message Counts  
Global Message Counts And Sizes:  
Message counts:  
recipients  
volume  
---------- ---------------  
3,203,820 36,046,885.7 kb  
94,457  
deliveries  
bounces  
total  
3,298,277 36,046,885.7 kb  
Message sizes:  
min. size avg. size max. size  
--------- --------- ---------  
2.1 kb  
11.3 kb  
122.4 kb  
This report list the basic numbers associated on the mailings being reported. Totals for  
delivered, bounced, and size of messages are included.  
11.4.2.5 Top Bounce  
Top Bounce Domain Breakdowns:  
domain recipients total bounced 5.X.X bounces 4.X.X bounces  
-------------- ---------- ------------- ------------- -------------  
aol.com  
earthlink.net  
gms.aol.com  
bellsouth.net  
msn.com  
yahoo.com  
gmail.com  
hotmail.com  
comcast.net  
verizon.net  
202,123  
35,028  
234,528  
28,401  
10,138  
1,548,313  
6,563  
207,995  
67,001  
12,338  
26,906  
12,148  
8,501  
7,647  
7,636  
4,197  
2,140  
1,650  
1,429  
1,344  
26,906  
12,148  
8,501  
7,647  
7,636  
4,197  
2,140  
1,650  
1,428  
107  
0
0
0
0
0
0
0
0
1
1,237  
...  
bellsouth.net  
domain recipients total bounced 5.X.X bounces 4.X.X bounces  
------------- ---------- ------------- ------------- -------------  
bellsouth.net  
28,401  
7,647  
7,647  
0
286  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
bounced %bounced dsn code (reason)  
------- -------- -----------------  
7,401  
149  
95  
96.8% 5.3.2 (system not accepting messages); 550 Too many invalid recipients  
1.9% 5.0.0 (undefined status); 550 Invalid recipient: ...@...  
1.2% 5.0.0 (undefined status); 501 #5.1.1 bad address ...@...  
0.0% 5.0.0 (undefined status); 550 Too many invalid recipients  
2
...  
The top bounce domain breakdown shows detailed bounce reasons for the top domains.  
By default, the top 10 domains (in terms of bounces) are printed, but this can be changed  
with the –topDomains num option. Data was removed from the above output to save  
space in this documents.  
For each domain the top bounce reasons are given as absolute number of bounces and as  
percentage of the bounces. The DSN (delivery status notification) code gives the reason  
for that bounce, as received by the foreign mail server. As a trade-off between detail and  
usability the DSN reason is only slightly modified (for example, email addresses in  
bounce messages are also replaced by ...@...to be able to generalize the bounces into  
bounce categories).  
So, while the total bounces breakdown provides an aggregated overview of the bounces,  
the top domains breakdown gives full detail on bounces grouped by domain.  
11.4.2.6 Top Domains  
Top Domains  
Domains with largest number of queued recipients:  
domain recipients bounced avg. time max. time %rcpt.  
---------------------- ---------- ------- --------- --------- ------  
aol.com  
hotmail.com  
yahoo.com  
webtv.net  
netzero.net  
92,891  
48,848  
34,355  
12,966  
7,648  
326  
1,028  
1,912  
104  
0:00:02  
0:00:12  
0:00:25  
5:12:28  
0:00:02  
0:01:23  
0:27:59  
0:28:42  
8:25:40  
0:00:28  
23.2%  
12.2%  
8.6%  
3.2%  
1.9%  
0
Domains with highest number of bounces:  
domain recipients bounced avg. time max. time %rcpt.  
---------------------- ---------- ------- --------- --------- ------  
yahoo.com  
hotmail.com  
earthlink.net  
worldnet.att.net  
juno.com  
34,355  
48,848  
4,958  
3,002  
5,039  
1,912  
1,028  
543  
353  
335  
0:00:25  
0:00:12  
0:00:07  
0:00:01  
0:00:02  
0:28:42  
0:27:59  
0:01:25  
0:00:13  
0:00:35  
8.6%  
12.2%  
1.2%  
0.7%  
1.3%  
Domains with highest average delivery times:  
domain recipients bounced avg. time max. time %rcpt.  
---------------------- ---------- ------- --------- --------- ------  
paris.net  
erpenbeck.com  
1
2
0
0
40:50:30  
27:57:24  
40:50:30  
47:13:33  
0.0%  
0.0%  
287  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
hvrsd.k12.nj.us  
in.usda.gov  
acbl.org  
1
3
2
0
0
0
21:42:25  
15:06:56  
12:53:25  
21:42:25  
39:49:46  
17:35:36  
0.0%  
0.0%  
0.0%  
This report shows the counts and throughput for the top domains based on:  
the largest number of recipients initially submitted and queued for delivery,  
the highest number of bounces handled by PowerMTA, and  
the highest average delivery times.  
The scope of the outputs are based on the type of report specified, i.e., global or by  
originator, envelope ID, or virtual mail transfer agent.  
For all three sections, the recipients column shows the total number of recipients  
submitted and queued for delivery for the domains, while the bounced column provides  
just the number of recipients that PowerMTA itself bounced (local bounces). Note that  
this is not a count of all of the bounces since any bounces happening after PowerMTA  
has transferred the message to an intermediate mailer count as successful transfers. The  
difference between the recipients and bounced columns is then the number of recipients  
that were successfully transferred by PowerMTA.  
For all three sections, the avg. time and max. time calculations are based on the  
difference between each message's queue timestamp and transfer timestamp. Only  
messages that were successfully delivered are included; bounces and other delivery  
reports are not. Messages transferred in multi-recipient (multi-"RCPT TO") SMTP  
transactions are broken down and each recipient is counted as a separate "delivery", each  
with its own transfer rate equal to that of the whole transaction itself. This is not an issue  
with single RCPT TO messages since messages delivered already equals recipients  
delivered.  
The avg. time is calculated by adding together all of the transfer times (transfer  
timestamp - queue timestamp) to the respective domain for each recipient, and then  
dividing this by the number of recipients to the domain. Using AOL as an example in the  
first output, one would read that it took an average of 2 seconds for each message for  
each recipient to be delivered, once each message was queued, for the 92,891 recipients  
at AOL.com.  
The max. time is the longest transfer time (transfer timestamp - queue timestamp) for  
one message to the respective domain. In the AOL case, one would read that the longest  
it took for one message to be delivered to AOL was 1 minute and 23 seconds.  
Conversely, all other messages to AOL for the 92,891 recipients were transferred in equal  
or less time.  
288  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
The %rcpt column provides the percentage of recipients submitted and queued for the  
domain to the total number of recipients across the scope of the report. For example,  
AOL's 92,891 queued recipients were 23.2% of the 400,761 total queued recipients.  
11.4.2.7 Top Rates  
Top Rates  
Top recipient delivery rates (including reports):  
measured over rcpt./min.  
recipients beginning on  
------------- ---------- ------------- -------------------  
one minute  
five minutes  
one hour  
19,896  
17,951  
16,245  
19,896 2003-04-03 02:02:05  
89,756 2003-04-03 05:10:27  
974,702 2003-04-03 04:28:34  
Top throughput rates (including reports):  
measured over  
kbyte/s  
kbytes beginning on  
------------- ---------- ------------- -------------------  
one minute  
five minutes  
one hour  
5,517.4  
3,989.6  
3,219.0  
331,045.8 2003-04-02 18:34:42  
1,196,891.6 2003-04-03 05:35:50  
11,588,374.9 2003-04-03 05:00:56  
This report shows the top throughput rates realized per recipient and the top data transfer  
rates during a time interval of one and five minutes and one hour. The scope of the output  
is always global and such is always based on the total numbers in the whole accounting  
file. All messages, normal deliveries as well as reports (including bounces) are taken into  
account when calculating these rates.  
The top recipient delivery rates are calculated for each time increment by sorting all  
accounting records by delivery time and then searching for the time interval during which  
the largest number of recipients were handled. This number is then entered in then  
recipients column. The rcpt./min. column provides a uniform recipient transfer  
measurement across the three time intervals, and is calculated by taking the numbers in  
the recipients column and dividing each by the number of minutes that make up each  
respective time interval (i.e. dividing the five minutes result by five and the one hour  
result by sixty). The messagescolumn shows the corresponding number of messages that  
were actually sent (i.e., number of SMTP transactions) while handling these recipients.  
This information is important when comparing performance numbers, since delivering a  
single message to multiple recipients is a lot less resource intensive than delivering  
individual messages.  
The top throughput rates are calculated in the same manner as the recipient delivery rates,  
however the top amount of data transferred per time interval is reported rather than the  
number of recipients. This transfer rate output is independent to the recipient delivery rate  
output, so they may or may not reflect the same messages. The kbytes/s column  
provides a uniform data transfer measurement across the three time increments, and is  
calculated by taking the numbers in the kbytescolumn and dividing each by the number  
of seconds that make up each respective time increment (i.e., dividing the five minutes  
289  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
result by 300 and the one hour result by 3600). The messages column shows the  
corresponding number of messages that were actually sent comprising the number of  
kilobytes shown.  
11.4.2.8 VMTA Summary  
VirtualMTA Traffic Summary:  
VirtualMTA  
IP address  
Recipients Delivered Bounced Bounced%  
------------------- -------------- ---------- --------- ------- --------  
vmta1  
vmta2  
vmta3  
vmta4  
vmta5  
vmta6  
vmta7  
vmta8  
192.168.0.97  
192.168.0.99  
192.168.0.98  
192.168.0.132  
192.168.0.134  
192.168.0.136  
192.168.0.135  
192.168.0.133  
192.168.0.87  
192.168.0.88  
192.168.0.86  
0.0.0.0  
192.168.0.171  
192.168.0.172  
192.168.0.168  
192.168.0.169  
192.168.0.170  
192.168.0.163  
192.168.0.158  
192.168.0.161  
192.168.0.164  
192.168.0.157  
192.168.0.162  
0.0.0.0  
489,134  
466,068  
461,980  
240,937  
195,063  
194,362  
192,084  
185,040  
123,175  
119,081  
111,882  
56,713  
45,823  
45,554  
45,461  
45,186  
44,714  
29,997  
29,201  
28,767  
28,287  
27,652  
27,377  
27,104  
8,526  
3,634  
3,348  
3,250  
3,247  
3,187  
3,128  
1,872  
1,693  
1,680  
1,590  
943  
489,134  
466,068  
461,980  
240,937  
195,063  
194,362  
192,084  
185,040  
123,175  
119,081  
111,882  
0
45,823  
45,554  
45,461  
45,186  
44,714  
29,997  
29,201  
28,767  
28,287  
27,652  
27,377  
0
0
0
0
0
0
0
0
0
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
100.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
100.0%  
100.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
100.0%  
100.0%  
100.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
100.0%  
vmta9  
0
0
0
vmta10  
vmta11  
vmta12  
vmta13  
vmta14  
vmta15  
vmta16  
vmta17  
vmta18  
vmta19  
vmta20  
vmta21  
vmta22  
vmta23  
vmta24  
vmta25  
vmta26  
vmta27  
vmta28  
vmta29  
vmta30  
vmta31  
vmta32  
vmta33  
vmta34  
vmta35  
vmta36  
vmta37  
vmta38  
(default)  
vmta39  
vmta40  
vmta41  
vmta42  
vmta43  
vmta44  
(default)  
56,713  
0
0
0
0
0
0
0
0
0
0
0
27,104  
8,526  
0.0.0.0  
0
192.168.0.126  
192.168.0.122  
192.168.0.124  
192.168.0.125  
192.168.0.121  
192.168.0.123  
192.168.0.200  
192.168.0.174  
192.168.0.173  
192.168.0.175  
0.0.0.0  
3,634  
3,348  
3,250  
3,247  
3,187  
3,128  
1,872  
1,693  
1,680  
1,590  
0
0
0
267  
33  
27  
27  
5
4
0
0
0
0
0
0
0
0
0
0
943  
782  
387  
0
0
0
0
0
0
0
0.0.0.0  
0.0.0.0  
782  
387  
267  
33  
27  
27  
5
4
192.168.0.238  
192.168.0.185  
192.168.0.184  
192.168.0.186  
192.168.0.181  
192.168.0.180  
192.168.0.182  
0.0.0.0  
3
2
3
0
2
Total  
3,298,277 3,203,820  
94,457  
2.9%  
VMTA Summary shows high level counters on the amount of messages that were sent to  
individual VirtualMTAs. This information includes a breakdown of deliveries, bounces,  
and percentage of bounces per VirtualMTA. The delivering IP is also included to help in  
determining if there is a reputation/sending issue with a given address.  
290  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
11.4.2.9 VMTA Time Breakdown  
VirtualMTA Traffic Breakdown By Time:  
VirtualMTA: vmta1, IP Address: 192.168.0.97  
Daily Breakdown:  
Date  
Recipients Delivered Bounced Bounced%  
---------- ---------- --------- ------- --------  
2007-01-16  
2007-01-17  
416,028  
73,106  
416,028  
73,106  
0
0
0.0%  
0.0%  
Hourly Breakdown:  
---------------------- 2007-01-16 ---------------------  
Interval Recipients Delivered Bounced Bounced%  
------------- ---------- --------- ------- --------  
00:00 - 00:59  
01:00 - 01:59  
02:00 - 02:59  
03:00 - 03:59  
04:00 - 04:59  
05:00 - 05:59  
06:00 - 06:59  
07:00 - 07:59  
08:00 - 08:59  
09:00 - 09:59  
10:00 - 10:59  
11:00 - 11:59  
12:00 - 12:59  
13:00 - 13:59  
14:00 - 14:59  
15:00 - 15:59  
16:00 - 16:59  
17:00 - 17:59  
18:00 - 18:59  
19:00 - 19:59  
20:00 - 20:59  
21:00 - 21:59  
22:00 - 22:59  
23:00 - 23:59  
0
0
0
0
1
207  
1
2
2
0
40  
35  
80  
140  
35  
0
0
0
0
0
0
1
207  
1
2
2
0
40  
35  
80  
140  
35  
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
3
3
24,712  
99,934  
92,585  
74,124  
68,374  
55,753  
24,712  
99,934  
92,585  
74,124  
68,374  
55,753  
---------------------- 2007-01-17 ---------------------  
Interval Recipients Delivered Bounced Bounced%  
------------- ---------- --------- ------- --------  
00:00 - 00:59  
01:00 - 01:59  
02:00 - 02:59  
03:00 - 03:59  
04:00 - 04:59  
05:00 - 05:59  
06:00 - 06:59  
07:00 - 07:59  
08:00 - 08:59  
09:00 - 09:59  
10:00 - 10:59  
11:00 - 11:59  
12:00 - 12:59  
13:00 - 13:59  
14:00 - 14:59  
15:00 - 15:59  
16:00 - 16:59  
17:00 - 17:59  
18:00 - 18:59  
19:00 - 19:59  
20:00 - 20:59  
67,536  
5,460  
67,536  
5,460  
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
104  
6
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
104  
6
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
291  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
21:00 - 21:59  
22:00 - 22:59  
23:00 - 23:59  
0
0
0
0
0
0
0
0
0
0.0%  
0.0%  
0.0%  
The VMTA time breakdown shows bounce counts for the top VirtualMTAs by time  
interval. By default all the VirtualMTAs are printed. For each VirtualMTA the bounce  
counts are given as absolute number of bounces and as percentage of the bounces for a  
given time period.  
11.4.2.10 VMTA Top Bounces  
VirtualMTA Top Bounce Domains:  
VirtualMTA: vmta1, IP Address: 192.168.0.97  
Domain  
Recipients Delivered Bounced Bounced%  
--------------- ---------- --------- ------- --------  
yahoo.com  
verizon.net  
aol.com  
sbcglobal.net  
juno.com  
netzero.net  
cox.net  
excite.com  
bellsouth.net  
netscape.com  
387,535  
18,710  
17,314  
14,241  
5,200  
3,186  
2,300  
957  
387,535  
18,710  
17,314  
14,241  
5,200  
3,186  
2,300  
957  
0
0
0
0
0
0
0
0
0
0
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
0.0%  
705  
594  
705  
594  
The VMTA Top Bounces report shows bounce counts for all the VirtualMTAs. By  
default, the top 20 domains (in terms of bounces) are printed, but this can be changed  
with the --topBounced <num> option.  
For each domain the top bounce reasons are given as absolute number of bounces and as  
percentage of the bounces. So, while the top bounces report provides an aggregated  
overview of the bounces, the VMTA top bounces report gives high level data on bounces  
grouped by VirtualMTA.  
11.5 The acctfind Accounting Reporting Application  
acctfind is a powerful accounting file search and reporting tool. It can be found in the  
\pmta\bin directory on Windows NT/2000, and in the /usr/sbin directory (named  
pmtaacctfind) on Unix.  
The tool is not required for exporting data from the accounting file because the file is no  
longer in a proprietary binary format.  
With the CSV accounting file written by  
PowerMTA, reporting can now be done without this tool. This tool, however, will still  
work with the CSV file format, and is provided to assist with extracting subsets of the  
data.  
292  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
acctfindallows one to search for records in the accounting file, as well as to produce a  
custom output based on specific fields in the matching records. For example, one can  
easily use acctfind to generate a list of all addresses that bounced with a persistent  
(5xx) error for a particular campaign, sorted by the bounce reason, in a tab separated  
output that contains the recipient address first, followed by the MAIL FROM/originator  
address, then the bounce code and reason.  
acctfind currently supports seven different output formats including standard, comma  
separated values, tab separated values, html, xml, "pretty" xml, and custom-defined  
outputs.  
This Section provides a quick overview of the feature set and options, along with sample  
commands, however the more detailed help obtained by passing the --help option to  
acctfinditself should be referenced for further insight.  
The general format for the command is  
acctfind [options] accounting files ...  
The top level segmentation options are based on the record types, which include  
searching for matches in records for messages successfully delivered (--delivered),  
bounce reports delivered (--bounced), run status records (--status), and general mta  
information (--mta).  
For example,  
acctfind --bounced acct.dat  
would search for matching records only among the bounce report records. If none of  
these are specified in the command, the default is to search for matches in both message  
delivered records and bounce report records.  
All of the fields in the accounting records (listed in Section 1.1.1 & Section 1.1.2) are  
available for matching (with the --match option), and the match pattern can be either a  
perl regular expression (e.g., m/^5\./) or some string for case-independent string  
matching.  
If you want to restrict the matching to some fields, you can do that by providing a list of  
fields to match enclosed in square brackets in front of the pattern (e.g. --match  
[from,to]port25.com).  
Shortcut options for matching single fields are also available. For example, --match  
[to]port25 is equivalent to --to port25. To further refine the output, more than one  
matching needle can be specified. For example, to get a listing of all yahoo.com  
293  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
addresses that bounced with a persistent (5xx) error, you would have the following option  
combinations in the command  
acctfind --bounced --dsnStatus m/^5\./ --to yahoo.com acct.dat  
As mentioned, seven different output formats are supported. You choose the desired  
format using the --output option, along with the format and the fields desired to be  
outputted. For example,  
acctfind --delivered --to hotmail.com --output csv[to,from,envid,vmta,dstIp] acct.dat  
would search all message delivered records for recipient addresses at hotmail.com and  
generate a comma separated output which lists, on each line,  
the hotmail recipient address,  
the message originator address,  
the envelope ID used for tracking the message,  
the VirtualMTA used to deliver the message, and  
the IP address of the Hotmail machine that accepted the message.  
To get an HTML output vs. csv output of the same, you would run  
acctfind --delivered --to hotmail.com --output html[to,from,envid,vmta,dstIp] acct.dat  
A full detailed listing and description of all of the options available can be found in the  
help by running acctfind --help. Included below are a few sample commands and  
options to help better understand the formats and capabilities. Do not hesitate to contact  
us at support@port25.com with any questions or when seeking the proper command  
sequence for a desired result.  
11.5.1 Examples  
1. To generate a list of all addressess that bounced in a comma separated output, that  
contains the recipient address first, followed by the MAIL FROM/originator address,  
then VirtualMTA used, then the bounce codes and reason, sorted by the bounce  
reason (DSN Diagnostics):  
acctfind --bounced --sortBy dsnDiag --output tsv[to,from,vmta,dsnStatus,dsnDiag] acct.dat  
Note that the --sortByoption is only supported on Unix at this time.  
2. To generate a list of all addresses that bounced with a persistent (5xx) error, in a  
comma separated output that contains the recipient address first, followed by the  
MAIL FROM/originator address, envelope ID, then the bounce code and reason:  
294  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
acctfind --bounced --dsnStatus m/^5\./ --output csv[to,from,envId,dsnStatus,dsnDiag] acct  
3. To generate a list of all hotmail.com addresses that bounced, in an HTML output  
that contains the recipient address, and bounce reasons:  
acctfind --bounced --to hotmail --output html[to,dsnStatus,dsnDiag] acct  
4. To generate a list of all hotmail.com addresses that were successfully transferred,  
in a "pretty XML" output that contains the recipient addresses, VirtualMTA used  
to deliver the messages, the queue and transfer time stamps in ISO format, and the  
IP address of the hotmail machine that accepted the messages:  
acctfind --iso-times --delivered --to hotmail --output  
prettyxml[to,vmta,timeQueued,timeDelivered,dstIp] acct.dat  
5. To search for a particular e-mail address (test@port25.com) to see whether it  
was delivered or bounced, with a tsv output showing the address, whether the  
message failed, and the ISO-formatted queue time and delivery time:  
acctfind --iso-times --to test@port25.com --output tsv[to,dsnAction,timeQueued,timeDelivered] acct.dat  
6. To search for a particular e-mail address (test@port25.com) to see whether it  
was delivered or bounced, with the standard output:  
acctfind --iso-times --to support acct.dat  
7. To search for a particular header that is being logged via the “acct-log-header”  
directive:  
acctfind --output csv[to,from,header:x-foobar] acct.dat  
11.6 Bounce Categories  
For easier classification of the actual reason for a bounce, pmtastats groups bounces in  
bounce categories. All bounces in a category have probably the same root cause, e.g. all  
messages in a category may be considered spam or another category may indicate the  
recipient is unknown. Using the various bounce codes and DSN reasons, pmtastats  
aggregates these message in likely bounce categories. This gives a good overview of why  
messages could not be delivered.  
295  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
The categories are customizable using the <bounce-category> tag (see Section 3.2). Any  
new or custom categories would be show in the pmtastats output as well as in the  
accounting file itself.  
The bounce category is included in the accounting file (the bounceCat tag, see Section  
1.1.1). It can be obtained directly from the CSV file or be used in acctfind.  
Currently, these bounce categories are defined:  
bad-configuration  
messages rejected due to configuration issues with remote  
host, 5.X.X error  
bad-connection  
messages bounced due to bad connection issues with remote  
host, 4.X.X error  
bad-domain  
messages bounced due to invalid or non-existing domains,  
5.X.X error  
bad-mailbox  
messages rejected due to bad, invalid, or non-existent  
recipient addresses, 5.X.X error  
content-related  
messages refused or blocked due to content related reasons,  
5.X.X error  
inactive-mailbox  
messages rejected due to expired, inactive, or disabled  
recipient addresses, 5.X.X error  
invalid-sender  
messages bounced due to invalid DNS or MX entry for  
sending domain  
message-expired  
messages bounced due to not being delivered before the  
bounce-after, 4.X.X error  
no-answer-from-host  
messages bounces due to receiving no response from remote  
host after connecting, 4.X.X or 5.X.X error  
other  
messages rejected due to other reasons, 4.X.X or 5.X.X error  
policy-related  
messages refused or blocked due to general policy reasons,  
5.X.X error  
protocol-errors  
messages rejected due to SMTP protocol syntax or sequence  
errors, 5.X.X error  
quota-issues  
messages rejected or blocked due to mailbox quota issues,  
4.X.X or 5.X.X error  
relaying-issues  
messages refused or blocked due to remote mail server  
relaying issues, 5.X.X error  
routing-errors  
messages bounced due to mail routing issues for recipient  
domain, 5.X.X error  
296  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
spam-related  
virus-related  
messages refused or blocked due to spam related reasons,  
5.X.X error  
messages refused or blocked due to virus related reasons,  
5.X.X error  
Note that this list and the classifications may be subject to change, since DSN status  
messages may vary.  
11.7 Libraries Available for Parsing CSV Records  
Each API example program shipped with the APIs also has a comment in the beginning  
of the file pointing to the CSV library being used.  
In API examples we use:  
JavaCSV (http://sourceforge.net/projects/javacsv/) is a free, easy to use Java CSV  
library. It can read the headers from the first line and then later in the program  
you can access individual fields by their name. (Or by number, if you wish.)  
Lumenworks CsvReader  
(http://www.codeproject.com/cs/database/CsvReader.asp) is a free library for  
.NET (you have to register with the codeproject website, though). We use it for  
the .NET API examples. It is similar to JavaCSV.  
CsvJDBC (http://csvjdbc.sourceforge.net) can be used like a JDBC driver that is  
based on a CSV file instead of a real database. It is not recommended for reading  
the CSV files, unless the programmer is very much used to JDBC and doesn't  
want to learn a new library. There are probably similar Microsoft classes in the  
ODBC area that do the same thing.  
With Text::CSV_XS you create a csv object that you can then ask to read and  
parse a line from a data source you provide (writing is also possible but not  
needed since the accounting files are only read). The easiest way to provide such  
a data source is to use the IO::Handle module that comes with Perl that allows  
you to pass an I/O handle as a data source.  
With the first call to the getline() method of the csv object you get an array with the  
column headers, with the subsequent calls you get an array with the data for one record in  
the same order as the column headers (this is because the first line in an accounting field  
contains the column headers, it's no special treatment from the getline() method). So  
access to the data is only possible by column index. If you want access by column  
headers the accountingByIp.pl and splitter.pl examples contain a sub that converts the  
array to a hash with the column headers as keys.  
297  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Beware of libraries that attempted to buffer (i.e., keep in memory) the whole CSV input.  
With the expected size of the accounting files, it would be strongly adviseable to not use  
such a memory intensive parser.  
We recommend against writing one's own CSV reader, as the CSV format can be more  
difficult to work with than it initially looks.  
298  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
12. Processing Inbound email  
12.1 Introduction  
There may be times when PowerMTA needs to handle inbound mail outside of messages  
created by a submission (e.g. list manager, CRM, etc.) application. These messages may  
be remote (asynchronous) bounces, corporate mail, or any other type of email originating  
from outside an organization’s infrastructure. In these cases, PowerMTA can accept the  
messages and do one of a few things with the messages. It can:  
Relay them to another mail server  
Deliver them to file on the local system  
Discard them (blackhole)  
Deliver to pipe (local mail processing application)  
Process asynchronous (remote) bounces  
Process feedback loop emails  
Any combination of these options may be used, and PowerMTA will create a subsequent  
delivery record in the accounting file for mail that is processed in one of these manners.  
Remote bounce and feedback loop parsing coming soon. Contact Port25 Solutions for  
more information.  
12.2 Relaying  
To relay messages to another mail server, PowerMTA will need to be configured to  
accept the messages, and then deliver them to their final destination.  
relay-domain yourdomain.com  
relay-domain otherdomain.com  
relay-address bounce@bounces.yourdomain.com  
<domain bounces.yourdomain.com>  
route [1.2.3.4]:25  
</domain>  
<domain otherdomain.com>  
route [5.6.7.8]:2525  
</domain>  
In the above example, messages for bounces.yourdomain.com are accepted for delivery  
and then forwarded to server 1.2.3.4 on port 25 and messages for otherdomain.com are  
forwarded to 5.6.7.8 on port 2525 and marked as such in the accounting file.  
12.3 Deliver to File  
299  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
       
To deliver messages to file, PowerMTA will need to be configured to accept the  
messages, and then deliver them to somewhere on the local disk system.  
relay-domain bounces.yourdomain.com  
relay-domain otherdomain.com  
relay-address bounce@bounces.yourdomain.com  
<domain bounces.yourdomain.com>  
type file  
file-format append-mbox  
file-destination /etc/pmta/inbound/$domain  
</domain>  
<domain otherdomain.com>  
type file  
file-format newfile-pickup  
file-destination /etc/pmta/inbound/$domain  
</domain>  
In the above example, messages for bounces.yourdomain.com and otherdomain.com are  
accepted for delivery and then each message is delivered to the individual files (based on  
domain) on the local disk and marked as such in the accounting file.  
12.4 Discarding  
To discard (blackhole) the inbound messages, PowerMTA will need to be configured to  
accept the messages, and then discard them based on domain.  
relay-domain bounces.yourdomain.com  
relay-domain otherdomain.com  
relay-address bounce@bounces.yourdomain.com  
<domain bounces.yourdomain.com>  
type discard  
</domain>  
<domain otherdomain.com>  
type discard  
</domain>  
In the above example, messages for bounces.yourdomain.com and otherdomain.com are  
accepted for delivery, then discarded and marked as such in the accounting file.  
12.5 Delivering to local application (pipe)  
To deliver messages to a local application via pipe, PowerMTA will need to be  
configured to accept the messages, and then deliver them based on domain.  
300  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
relay-domain bounces.yourdomain.com  
relay-domain otherdomain.com  
relay-address bounce@bounces.yourdomain.com  
<domain bounces.yourdomain.com>  
type pipe  
command "/my/bounce/processor --envid \"$envid\" \"$user\""  
</domain>  
<domain otherdomain.com>  
type pipe  
command "/my/bounce/processor --envid \"$envid\" \"$user\""  
</domain>  
In the above example, messages for bounces.yourdomain.com and otherdomain.com are  
accepted for delivery, then piped to the custom application (with associated parameters)  
on the local file system and marked as such in the accounting file.  
12.6 Processing Asynchronous (Remote) Bounces and  
remote status reports  
Remote bounce processing works as a "filter" located after receipt of an email and before  
it is routed to a delivery queue. If PowerMTA recognizes the format and no errors occur  
while processing it, it writes a new type of accounting record ("rb" and "rs", see below).  
For those emails you have the option of ending the email there or letting it pass to regular  
delivery. If the message isn't recognized or an error occurs, it is passed to a delivery  
queue and delivered normally (by whatever method assigned to the domain -- usually  
'file' or 'pipe').  
As a note, the same domain and/or address for <address-list> can be used for both remote  
bounces and feedback loops. If this is done, PowerMTA will check the message first for  
a remote bounce, then if unmatched, for a feedback loop email.  
The email address used should be unique for each email sent to allow for more detailed  
tracking. For example, instead of:  
bounce@bounce.yourdomain.com  
The following should be considered instead:  
customer1-campiagn563-uniquieID498294@bounce.yourdomain.com  
Accounting Records:  
There are two kinds of records for asynchronous bounces: "rb" for remote bounce and  
"rs" for reporting other kinds of remote status (used for DSN positive and "delayed"  
status notifications). Most people will only be interested in "rb" records. The following  
columns are available for these records:  
301  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
Name  
timeLogged  
orig  
Description  
current time  
originator (taken from report's recipient address)  
(final) recipient  
rcpt  
orcpt  
original recipient  
DSN action  
DSN status  
DSN diagnostic  
DSN remote MTA  
dsnAction  
dsnStatus  
dsnDiag  
dsnMta  
dsnReportingMta DSN reporting MTA  
bounceCat  
srcType  
srcMta  
bounce category  
type of source from which the report was received  
MTA from which the report was received  
envelope ID  
envId  
header_<name>  
header extracted from original email  
Configuration:  
You define a list of email addresses that are bounce addresses, i.e., original MAIL FROM  
addresses. Only email received for those addresses gets filtered/looked at looking for  
bounces. Use of the following requires a restart of the PowerMTA service. You can  
define entire domains which get filtered, or for more granular control you can use regular  
expressions to match entire addresses with the option to deliver recognized emails is  
configured as:  
<bounce-processor>  
deliver-email yes  
# default: no  
forward-unmatched-to auto-feedback@port25.com  
forward-errors-to auto-feedback@port25.com  
<address-list>  
domain domain.to.filter  
address /regex@domain.to.filter/  
# whole domain  
# regex  
</address-list>  
</bounce-processor>  
#
# Required for delivery of emails regardless of  
# deliver-emails being set to yes or no  
#
<domain domain.to.filter>  
route [1.2.3.4]:25  
</domain>  
The accounting records are configured just like the other types in the configuration. The  
example below has both local (sync) and remote (async) bounces written to the same file,  
and includes a custom "x-id" header:  
302  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
<acct-file /var/log/pmta/bounces.csv>  
records b, rb  
record-fields b *,header_x-id  
record-fields rb *,header_x-id  
</acct-file>  
<acct-file /var/log/pmta/status.csv>  
records rs  
record-fields rs *,header_x-id  
</acct-file>  
After intial configuration a restart of the PowerMTA service is required for asynchronous  
bounce processing to work.  
If you are having trouble, and need to turn on logging, setting the following global  
directive:  
<domain {bounce}>  
log-messages yes  
</domain>  
12.7 Processing Feedback Loop Emails  
To enable feedback loop processing, you add something like:  
<feedback-loop-processor>  
deliver-email no  
forward-unmatched-to auto-feedback@port25.com  
forward-errors-to auto-feedback@port25.com  
<address-list>  
address /fbl@fbl.yourdomain.com/  
</address-list>  
</feedback-loop-processor>  
#
# Required for delivery of emails regardless of  
# deliver-emails being set to yes or no  
#
<domain mydomain.com>  
route [1.2.3.4]:25  
</domain>  
to the configuration file. The "forward-..." directives can be specified more than once to  
have email forward to multiple addresses. "<address-list>" accepts individual domains  
like in "domain foo.com" and regular expressions like in the example above, so you have  
great flexibility in specifying the addresses for which we should attempt FBL processing.  
As with bounce processing, you have the option to continue to deliver the emails after  
303  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
processing (e.g., to save them all to a folder) or to have them end there. Unmatched or  
failed emails always proceed to delivery.  
As a note, the same domain and/or address for <address-list> can be used for both remote  
bounces and feedback loops. If this is done, PowerMTA will check the message first for  
a remote bounce, then if unmatched, for a feedback loop email.  
The email address used should be something easy to parse. For example:  
fbl@fbl.yourdomain.com  
PowerMTA should be the MX to handle these messages. If there are MTAs that handle  
the messages prior to being delivered to PowerMTA, PowerMTA may be unable to  
recognize the message as a FBL email.  
To allow for more detailed tracking a custom header may be added to the email  
(assuming the remote mailer doesn’t redact the header).  
x-tracker: customer1-campiagn563-uniquieID498294  
Custom headers are not included by default in the PowerMTA accounting file, so if the  
above header is needed in the accounting make sure to add it as a custom header.  
Emails matching the address list go into a special {feedbackLoop} queue, where they are  
processed. You need also configure an accounting file to receive the resulting data:  
<acct-file /var/log/pmta/fbl.csv>  
records feedback-loop  
record-fields f *,header_subject  
</acct-file>  
After intial configuration a restart of the PowerMTA service is required for feedback loop  
processing to work. "f" and "feedback-loop" can be used for the record name  
interchangeably. In the accounting file you actually see 'f'. The available columns (all of  
which, except for 'header', are included by default) are:  
The following columns are available for f records:  
Name  
timeLogged  
format  
Description  
current time  
"arf" or "jmrp"  
userAgent  
envId  
name & version of the program that generated the report  
envelope ID  
orig  
rcpt  
originator (taken from report's recipient address)  
(final) recipient  
reportingMta  
sourceIp  
the name of the MTA generating this feedback report  
address of MTA from which the message was received  
304  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
header_<name>  
arf_<name>  
header extracted from original email  
field from ARF feedback-report  
'header_From', 'header_Return-Path', 'header_X-job' and 'header_Subject' are included by  
default.  
If a feedback report includes multiple recipients, a separate 'f' record is written for each  
recipient, repeating any common fields. Since a field requested via 'arf_...' may occur  
multiple times in the report, the column may contain a (CSV-encoded) list of values.  
12.8 Tracking a campaign in PowerMTA with a JobID  
To track campaigns in PowerMTA it is best to use an x-job header. This will show as a  
JobID or a Job in PowerMTA and PowerMTA Management Console. For this to work  
properly the application feeding PowerMTA needs to set an x-job header. The value of  
this header should be unique to each campaign. For example:  
x-job: UniqueID-Date  
With this set, PowerMTA needs to know to look for the header with a setting similar to  
the following:  
<source 0/0>  
process-x-job yes  
</source>  
If needed, an alternate header may be used with something similar to the following:  
<source 0/0>  
jobid-header x-custom-header  
process-x-job yes  
</source>  
In the above example x-custom-header will be used as the JobID in place of x-job.  
Once the above is set, PowerMTA will log the JobID to the accounting file once a  
delivery or bounce has been taken place. Information about messages still in the queue  
can be found on the Jobs tab of the PowerMTA web monitor or by using the “pmta show  
jobs” command.  
Lastly, additional information about current queue and historical reporting can by found  
in the PowerMTA Management Console dashboard, monitoring, and reporting sections.  
A. Deprecated APIs  
305  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
A.1. Submission API  
The C submission API consists of a header file (submit.h) as well as code included in a  
library file. By including the supplied header file and using the fuctions provided in the  
library, C/C++ programs can write directly into PowerMTA's spool.  
A.1.1. Using the C Submission API  
To send a message through the C submission API, you  
1. Obtain a submission context by calling SUBMIT_NewContext;  
2. Start a new message submission with SUBMIT_StartMessage;  
3. Set the message's originator with SUBMIT_SetOriginator and specify the  
recipients by calling SUBMIT_AddRecipientfor each of them;  
4. Optionally call SUBMIT_AddHeaderto specify custom message headers;  
5. Use a combination of SUBMIT_AddContentLine, SUBMIT_AddContentLineLen  
and SUBMIT_AddContentBlockto provide the message body;  
6. Finish the message, completing the submission, with SUBMIT_FinishMessage.  
7. When done submitting messages, discard the submission context using  
SUBMIT_DeleteContext.  
Upon the first usage of SUBMIT_AddContentLine, SUBMIT_AddContentLineLen or  
SUBMIT_AddContentBlock, the API automatically supplies any missing headers and adds  
the empty line separating the message headers from the body. Header completion is  
performed as follows:  
If the From: header is missing (i.e., it has not been added using  
SUBMIT_AddHeader), it is automatically added based on the message's originator  
(specified with SUBMIT_SetOriginator);  
If the Date:header is missing, it is added.  
Note that you can (and should, for best performance) continue to use the submission  
context to submit more messages after the first submission is completed. If your program  
is multithreaded, each thread should obtain and use its own submission context.  
A.1.2. Function Reference  
SUBMIT_NewContext  
Creates a new submission context  
SUBMIT_CTX* SUBMIT_NewContext()  
Description:  
Creates a new submission context. Zero is returned if not enough memory can be  
306  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
     
allocated.  
SUBMIT_ResetContext  
Resets the submission context  
void SUBMIT_ResetContext(SUBMIT_CTX* ctx)  
Arguments:  
ctx  
Submission context  
Description:  
Resets the specified submission context, discarding the message currently being  
submitted, if not yet finished.  
SUBMIT_DeleteContext  
Deletes the submission context  
void SUBMIT_DeleteContext(SUBMIT_CTX* ctx)  
Arguments:  
ctx  
Submission context  
Description:  
Deletes the specified submission context, reclaiming memory and other resources. If  
the message currently being submitted has not yet been finished, it is discarded.  
SUBMIT_StartMessage  
Starts the submission of a new message  
BOOL SUBMIT_StartMessage(SUBMIT_CTX* ctx, const char* envelopeId,  
unsigned flags)  
Arguments:  
ctx  
Submission context  
envelopeId  
Envelope ID for the message.  
307  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
flags  
A combination of:  
SUBMIT_MSG_RETURN_HEADERS  
Specifies that any reports (e.g., bounces)  
should include only the message's headers.  
SUBMIT_MSG_RETURN_FULL  
SUBMIT_MSG_BODY_7BIT  
SUBMIT_MSG_BODY_8BIT  
SUBMIT_MSG_BODY_BINARY  
Specifies that any reports (e.g., bounces)  
should include the full messsage.  
Specifies that the message being submitted  
only includes 7-bit data.  
Specifies that the message being submitted  
contains 8-bit (but not binary) data.  
Specifies that the message being submitted  
has binary contents. Since binary contents  
are not yet currently supported, this option  
is a placeholder only. To provide binary  
content, you must first encode it (e.g., using  
base64 encoding).  
SUBMIT_MSG_OPT_VERP  
Enables the VERP (Variable Envelope  
Return Path) extension. This non-standard  
SMTP  
extension  
is  
described  
in  
http://www.port25.com/support/rfcs/draft-  
varshavchik-verp-smtpext-03.txt.  
Description:  
Starts the submission of a new message. In case of a failure, zero is returned and the  
error text can be obtained by calling SUBMIT_GetLastError.  
The RETURN and BODY flags are equivalent to specifying the RETURN= and BODY=  
parameters in the ESMTP MAILcommand.  
If none of the RETURN flags are specified, the mailer generating the report decides  
whether just the headers or the full message will be returned. In the case of reports  
generated by PowerMTA, only the headers are returned.  
If none of the BODY flags are specified, the default is 8 bits.  
SUBMIT_SetOriginator  
Sets the message's originator  
BOOL SUBMIT_SetOriginator(SUBMIT_CTX* ctx, const char* address)  
308  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Arguments:  
ctx  
Submission context  
address  
Originator's e-mail address  
Description:  
Sets the message's originator. In case of a failure, zero is returned and the error text can  
be obtained by calling SUBMIT_GetLastError.  
SUBMIT_AddRecipient  
Adds a recipient  
BOOL SUBMIT_AddRecipient(SUBMIT_CTX* ctx, const char* address,  
unsigned flags)  
Arguments:  
ctx  
Submission context  
address  
Recipient's e-mail address  
flags  
A combination of:  
SUBMIT_RCPT_NOTIFY_SUCCESS  
Specifies that a delivery report should be  
sent in case the delivery succeeds.  
SUBMIT_RCPT_NOTIFY_FAILURE  
Specifies that a delivery report should be  
sent in case the delivery fails.  
SUBMIT_RCPT_NOTIFY_DELAY  
Specifies that a delivery report should be  
sent in case the delivery is delayed.  
SUBMIT_RCPT_NOTIFY_NEVER  
Specifies that a no delivery report should  
be sent.  
SUBMIT_RCPT_CHECK_VALIDITY  
Specifies that the e-mail address should be  
checked for validity.  
Description:  
Adds a recipient to the current message. In case of a failure, zero is returned and the  
error text can be obtained by calling SUBMIT_GetLastError.  
309  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
The NOTIFY flags are equivalent to specifying the DSN NOTIFY= parameter in the  
ESMTP RCPTcommand. If any of these are specified, they are used by PowerMTA as  
well as passed on to the receiving mailer — as mandated by DSN.  
If none of the NOTIFY flags are specified, the mailer's default is used: if the message  
has not yet been transferred to another mailer, PowerMTA notifies of failures only. If  
the message has been passed to a different mailer, that mailer decides what to do. To  
prevent PowerMTA from sending a bounce (delivery failure notification), you must  
specify SUBMIT_RCPT_NOTIFY_NEVER with no other NOTIFY flags. Naturally, if no  
originator address has been specified, no notifications can be sent (or requested).  
SUBMIT_AddHeader  
Adds a header  
BOOL SUBMIT_AddHeader(SUBMIT_CTX* ctx, const char* keyword,  
const char* content)  
Arguments:  
ctx  
Submission context  
keyword  
Name of header to add  
content  
Content of header  
Description:  
Adds a header line to the current message. In case of a failure, zero is returned and the  
error text can be obtained by calling SUBMIT_GetLastError.  
SUBMIT_AddContentLine  
Adds a content line  
BOOL SUBMIT_AddContentLine(SUBMIT_CTX* ctx, const char* line)  
Arguments:  
ctx  
Submission context  
line  
Null-terminated line to add  
310  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Description:  
Adds a line to the current message's body. In case of a failure, zero is returned and the  
error text can be obtained by calling SUBMIT_GetLastError.  
The line passed should be a standard C string, i.e., a '\0'-terminated array of characters.  
It may not contain any carriage return or line feed characters — PowerMTA appends  
these automatically.  
SUBMIT_AddContentLineLen  
Adds a content line of known length  
BOOL SUBMIT_AddContentLineLen(SUBMIT_CTX* ctx, const char* line,  
unsigned length)  
Arguments:  
ctx  
Submission context  
line  
Line to add  
length  
Length of line  
Description:  
Adds a line to the current message's body. In case of a failure, zero is returned and the  
error text can be obtained by calling SUBMIT_GetLastError.  
The line passed should be an array of characters, not necessarily '\0'-terminated. It may  
not contain any carriage return or line feed characters — PowerMTA appends these  
automatically.  
SUBMIT_AddContentBlock  
Adds a block of content  
BOOL SUBMIT_AddContentBlock(SUBMIT_CTX* ctx, const char* block,  
unsigned length)  
Arguments:  
ctx  
Submission context  
block  
311  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Data block to add  
Length of block  
length  
Description:  
Adds a block of data to the current message's body. In case of a failure, zero is returned  
and the error text can be obtained by calling SUBMIT_GetLastError.  
The data block may contain several lines. Any lines in the block must be properly  
terminated with carriage return and line feed, as mandated by e-mail standards.  
SUBMIT_AttachFile  
Attaches a file to the message body  
BOOL SUBMIT_AttachFile(SUBMIT_CTX* ctx, const char* filename,  
const char* contentType)  
Arguments:  
ctx  
Submission context  
filename  
Full path to file to attach  
contentType  
value Content-Typeheader, e.g. application/content-stream  
Description:  
Attaches a file to the message body. It adds the Content-Type, Content-  
Disposition and Content-Transfer-Encoding MIME headers, a blank line, and  
follows with the file contents, base64-encoded.  
To attach a file, you should thus add the MIME boundary line just before using  
SUBMIT_AttachFile. In case of a failure, zero is returned and the error text can be  
obtained by calling SUBMIT_GetLastError.  
SUBMIT_FinishMessage  
Finishes submitting a message  
BOOL SUBMIT_FinishMessage(SUBMIT_CTX* ctx)  
Arguments:  
312  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
ctx  
Submission context  
Description:  
Finishes the current message and dispatches it. In case of a failure, zero is returned and  
the error text can be obtained by calling SUBMIT_GetLastError.  
SUBMIT_GetLastError  
Returns the last error occurred  
char* SUBMIT_GetLastError(SUBMIT_CTX* ctx)  
Arguments:  
ctx  
Submission context  
Description:  
Returns a description of the last error encountered in the specified submission context.  
Call this function a) only after in fact an error occured, and b) right after the error  
occured, i.e. without calling any other of the PMTA API functions.  
A.2. Perl Submission API  
The Perl submission API consists of a perl module, (Submitter.pm), which provides  
functions that allow Perl programs to submit messages and write directly to PowerMTA's  
spool. Since the Perl API is basically a software interface to the C submission API, their  
inner workings are identical and so we recommend reading through Section B.1.1 before  
using the Perl API.  
A.2.1. Function Reference  
new  
Creates new submitter object  
$ctx = new Submitter;  
Description:  
313  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
   
Creates a new submitter object. The submitter is a regular Perl object.  
Zero is returned if not enough memory can be allocated.  
Reset  
Resets the submitter  
$ctx->Reset ();  
Description:  
Resets the submitter, discarding the message currently being submitted, if not yet  
finished.  
StartMessage  
Starts the submission of a new message  
$ok = $ctx->StartMessage ($envelopeId, $flags);  
Arguments:  
envelopeId  
Envelope ID for the message.  
flags  
A combination of:  
MSG_RETURN_HEADERS  
Specifies that any reports (e.g., bounces) should  
include only the message's headers.  
MSG_RETURN_FULL  
Specifies that any reports (e.g., bounces) should  
include the full messsage.  
MSG_BODY_7BIT  
Specifies that the message being submitted only  
includes 7-bit data.  
MSG_BODY_8BIT  
Specifies that the message being submitted contains  
8-bit (but not binary) data.  
MSG_BODY_BINARY  
Specifies that the message being submitted has  
binary contents. Since binary contents are not yet  
currently supported, this option is a placeholder  
only. To provide binary content, you must first  
encode it (e.g., using base64 encoding).  
MSG_OPT_VERP  
Enables the VERP (Variable Envelope Return Path)  
314  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
extension. This non-standard SMTP extension is  
described  
in  
http://www.port25.com/support/rfcs/draft-  
varshavchik-verp-smtpext-03.txt.  
Description:  
Starts the submission of a new message. In case of a failure, zero is returned and the  
error text can be obtained by calling GetLastError.  
The RETURN and BODY flags are equivalent to specifying the RETURN= and BODY=  
parameters in the ESMTP MAILcommand.  
If none of the RETURN flags are specified, the mailer generating the report decides  
whether just the headers or the full message will be returned. In the case of reports  
generated by PowerMTA, only the headers are returned.  
If none of the BODY flags are specified, the default is 8 bits.  
SetOriginator  
Sets the message's originator  
$ok = $ctx->SetOriginator ($address);  
Arguments:  
address  
Originator's e-mail address, such as 'support@port25.com'  
Description:  
Sets the message's originator. In case of a failure, zero is returned and the error text can  
be obtained by calling GetLastError.  
AddRecipient  
Adds a recipient  
$ok = $ctx->AddRecipient ($address, $flags);  
Arguments:  
address  
Recipient's e-mail address, such as 'support@port25.com'  
315  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
flags  
A combination of:  
RCPT_NOTIFY_SUCCESS  
Specifies that a delivery report should be sent in  
case the delivery succeeds.  
RCPT_NOTIFY_FAILURE  
RCPT_NOTIFY_DELAY  
Specifies that a delivery report should be sent in  
case the delivery fails.  
Specifies that a delivery report should be sent in  
case the delivery is delayed.  
RCPT_NOTIFY_NEVER  
Specifies that a no delivery report should be sent.  
RCPT_CHECK_VALIDITY  
Specifies that the e-mail address should be checked  
for validity.  
Description:  
Adds a recipient to the current message. In case of a failure, zero is returned and the  
error text can be obtained by calling GetLastError.  
The NOTIFY flags are equivalent to specifying the DSN NOTIFY= parameter in the  
ESMTP RCPTcommand. If any of these are specified, they are used by PowerMTA as  
well as passed on to the receiving mailer — as mandated by DSN.  
If none of the NOTIFY flags are specified, the mailer's default is used: if the message  
has not yet been transferred to another mailer, PowerMTA notifies of failures only. If  
the message has been passed to a different mailer, that mailer decides what to do. To  
prevent PowerMTA from sending a bounce (delivery failure notification), you must  
specify RCPT_NOTIFY_NEVER with no other NOTIFY flags. Naturally, if no originator  
address has been specified, no notifications can be sent (or requested).  
AddHeader  
Adds a header  
$ok = $ctx->AddHeader ($keyword, $content);  
Arguments:  
keyword  
Name of header to add, such as 'To'  
content  
Content  
of  
header,  
such  
as 'All  
subscribers  
<list-  
all@my.company.com>'  
316  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Description:  
Adds a header line to the current message. In case of a failure, zero is returned and the  
error text can be obtained by calling GetLastError.  
AddContentLine  
Adds a content line  
$ok = $ctx->AddContentLine ($line);  
Arguments:  
line  
Line to add  
Description:  
Adds a line to the current message's body. In case of a failure, zero is returned and the  
error text can be obtained by calling GetLastError.  
The line passed should be a string, which may not contain any carriage return or line  
feed characters — PowerMTA appends these automatically.  
AddContentBlock  
Adds a block of content  
$ok = $ctx->AddContentBlock ($block);  
Arguments:  
block  
Data block to add  
Description:  
Adds a block of data to the current message's body. In case of a failure, zero is returned  
and the error text can be obtained by calling GetLastError.  
The data block may contain several lines. Any lines in the block must be properly  
terminated with carriage return and line feed, as mandated by e-mail standards.  
FinishMessage  
317  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Finishes message and dispatches it  
$ok = $ctx->FinishMessage ();  
Description:  
Finishes the current message and dispatches it. In case of a failure, zero is returned and  
the error text can be obtained by calling GetLastError.  
GetLastError  
Returns a description of the last error  
$error = $ctx->GetLastError ();  
Description:  
Returns the description of the last error occurred, if any.  
Call this function a) only after in fact an error occured, and b) right after the error  
occured, i.e. without calling any other of the PMTA API functions.  
318  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
Acknowledgments  
Regular expression support is provided by the PCRE library package, which is open  
source software, written by Philip Hazel, and copyright by the University of Cambridge,  
England. PCRE is available from  
ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/.  
PowerMTA uses, and may in its distribution kits include, OpenSSL. The OpenSSL  
license requires that we reproduce it here:  
/* ====================================================================  
* Copyright (c) 1998-2006 The OpenSSL Project. All rights reserved.  
*
* Redistribution and use in source and binary forms, with or without  
* modification, are permitted provided that the following conditions  
* are met:  
*
* 1. Redistributions of source code must retain the above copyright  
*
*
notice, this list of conditions and the following disclaimer.  
* 2. Redistributions in binary form must reproduce the above copyright  
*
*
*
*
notice, this list of conditions and the following disclaimer in  
the documentation and/or other materials provided with the  
distribution.  
* 3. All advertising materials mentioning features or use of this  
*
*
*
*
software must display the following acknowledgment:  
"This product includes software developed by the OpenSSL Project  
for use in the OpenSSL Toolkit. (http://www.openssl.org/)"  
* 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to  
*
*
*
*
endorse or promote products derived from this software without  
prior written permission. For written permission, please contact  
openssl-core@openssl.org.  
* 5. Products derived from this software may not be called "OpenSSL"  
*
*
*
nor may "OpenSSL" appear in their names without prior written  
permission of the OpenSSL Project.  
* 6. Redistributions of any form whatsoever must retain the following  
*
*
*
*
acknowledgment:  
"This product includes software developed by the OpenSSL Project  
for use in the OpenSSL Toolkit (http://www.openssl.org/)"  
* THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY  
* EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE  
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR  
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR  
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,  
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT  
319  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
* NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;  
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)  
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,  
* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)  
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED  
* OF THE POSSIBILITY OF SUCH DAMAGE.  
* ====================================================================  
*
* This product includes cryptographic software written by Eric Young  
* (eay@cryptsoft.com). This product includes software written by Tim  
* Hudson (tjh@cryptsoft.com).  
*
*/  
Original SSLeay License  
-----------------------  
/* Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)  
* All rights reserved.  
*
* This package is an SSL implementation written  
* by Eric Young (eay@cryptsoft.com).  
* The implementation was written so as to conform with Netscapes SSL.  
*
* This library is free for commercial and non-commercial use as long as  
* the following conditions are aheared to. The following conditions  
* apply to all code found in this distribution, be it the RC4, RSA,  
* lhash, DES, etc., code; not just the SSL code. The SSL documentation  
* included with this distribution is covered by the same copyright terms  
* except that the holder is Tim Hudson (tjh@cryptsoft.com).  
*
* Copyright remains Eric Young's, and as such any Copyright notices in  
* the code are not to be removed.  
* If this package is used in a product, Eric Young should be given attribution  
* as the author of the parts of the library used.  
* This can be in the form of a textual message at program startup or  
* in documentation (online or textual) provided with the package.  
*
* Redistribution and use in source and binary forms, with or without  
* modification, are permitted provided that the following conditions  
* are met:  
* 1. Redistributions of source code must retain the copyright  
*
notice, this list of conditions and the following disclaimer.  
* 2. Redistributions in binary form must reproduce the above copyright  
*
*
notice, this list of conditions and the following disclaimer in the  
documentation and/or other materials provided with the distribution.  
* 3. All advertising materials mentioning features or use of this software  
*
*
*
*
*
must display the following acknowledgement:  
"This product includes cryptographic software written by  
Eric Young (eay@cryptsoft.com)"  
The word 'cryptographic' can be left out if the rouines from the library  
being used are not cryptographic related :-).  
* 4. If you include any Windows specific code (or a derivative thereof) from  
*
the apps directory (application code) you must include an acknowledgement:  
320  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
*
*
"This product includes software written by Tim Hudson (tjh@cryptsoft.com)"  
* THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND  
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE  
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE  
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE  
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL  
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS  
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)  
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT  
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY  
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF  
* SUCH DAMAGE.  
*
* The licence and distribution terms for any publically available version or  
* derivative of this code cannot be changed. i.e. this code cannot simply be  
* copied and put under another distribution licence  
* [including the GNU Public Licence.]  
*/  
321  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
DIRECTIVES INDEX  
acct-file  
count-moved-records, 69  
delete-after, 64  
iso-times, 65  
map-header-to-field, 66  
max-size, 65  
move-interval, 64  
move-to, 64  
record-fields, 68  
records, 67  
retry-interval, 65  
sync, 69  
user-string, 65  
world-readable, 68  
write-timeout, 66  
address-list  
address, 35  
domain, 35  
alphabetical  
accept-invalid-recipients, 95  
acct-auto-rotation, 69  
acct-file, 70  
acct-log-header, 70  
acct-move-interval, 71  
acct-move-max-size, 72  
acct-rotate, 70, 71  
acct-user-string, 72  
acct-write-msgDlv, 73  
add-date-header, 36  
add-message-id-header, 37, 116  
add-received-header, 37, 117  
address, 35  
allow-auth, 37  
allow-cancel-during-transfer, 96  
allow-mailmerge, 38  
allow-priority-interruption, 75  
allow-priority-interruption-during-transfer, 75  
allow-starttls, 39  
allow-unencrypted-plain-auth, 39  
always-allow-api-submission, 114  
always-allow-relaying, 32  
assume-delivery-upon-data-termination-timeout, 108  
assume-delivery-upon-data-termination-timeout, 97  
authentication-method, 40  
auth-password, 97  
auth-username, 96  
auto-cold-virtual-mta, 90  
auto-qualify-domain, 125  
backoff-max-connect-rate, 105  
322  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
 
backoff-max-msg-per-hour, 87  
backoff-max-msg-rate, 86  
backoff-notify, 88  
backoff-reroute-to-virtual-mta, 93  
backoff-retry-after, 87  
backoff-to-normal-after, 88  
backoff-to-normal-after-delivery, 88  
backoff-upon-all-sources-disabled, 89  
bcc, 36  
bounce-after, 75  
bounce-upon-5xx-greeting, 98  
bounce-upon-no-mx, 98  
bounce-upon-pix-transfer-failure, 99  
bounce-upon-transfer-failure, 99  
broken-auth-clients, 40  
check-dkim-inbound, 41  
check-domainkeys-inbound, 41  
check-mfrom-inbound, 43  
check-mfrom-inbound-best-guess, 44  
check-mfrom-outbound, 43  
check-pra-inbound, 44  
check-pra-inbound-best-guess, 44  
check-pra-outbound, 44  
cold-virtual-mta, 91  
command, 113  
connect-timeout, 100  
count-moved-records, 69  
data-send-timeout, 101  
date-header-time, 36  
default-smtp-port, 108  
default-virtual-mta, 45, 115  
delete-after, 64  
delete-file-holders, 30  
deliver-email, 34  
deliver-local-dsn, 74  
deliver-only, 31  
delivery-priority, 76  
disconnect-on-transient-error, 46  
dkim-identity, 77  
dkim-identity-fallback, 78  
dkim-sign, 76  
dk-sign, 76  
domain, 35  
domain-key, 79  
domain-macro, 94  
domain-suffix, 127  
dsn-return-default, 45, 115  
dummy-smtp-await-slot, 118  
dummy-smtp-has-chunking, 118  
dummy-smtp-has-pipelining, 119  
dummy-smtp-has-verp, 119  
dummy-smtp-ip, 118  
dummy-smtp-latency, 119  
dummy-smtp-port, 118  
dummy-smtp-update-stats, 119  
file-destination, 111  
file-format, 110  
forward-errors-to, 35  
forward-unmatched-to, 34  
header, 121  
323  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
hide-message-source, 46, 117  
host-id, 126  
host-name, 128  
http-access, 56  
http-log-data, 57  
http-log-requests, 57  
http-mgmt-port, 56  
http-mgmt-source, 57  
ignore-8bitmime, 101  
ignore-chunking, 102  
ignore-pipelining, 102  
include, 128  
include-headers-from, 94  
invalid-virtual-mta-fallback, 80  
iso-times, 65  
jobid-header, 49  
log-auto-rotation, 57  
log-commands, 60, 82  
log-connections, 59, 81  
log-data, 61, 83  
log-file, 58  
log-file-world-readable, 62  
log-resolution, 46, 59  
log-rotate, 58  
log-tls, 80  
log-transfer-failures, 47, 62  
mail-from, 121  
map-header-to-field, 66  
max-cold-virtual-mta-msg, 92  
max-connect-rate, 105  
max-errors-per-connection, 43  
max-events-recorded, 63, 84  
max-message-hops, 47  
max-message-size, 47  
max-msg-per-connection, 103  
max-msg-per-hour, 87  
max-msg-rate, 86  
max-rcpt-per-message, 47, 103, 112  
max-rcpt-per-transaction, 103  
max-size, 65  
max-smtp-in, 52  
max-smtp-msg-rate, 85  
max-smtp-out, 104  
max-smtp-out-per-source-ip, 104  
min-free-space, 31  
move-interval, 64  
move-to, 64  
mx-connection-limit, 107  
name-server, 129  
no-http-mgmt-source, 57  
password, 40  
pattern-list, 48, 117  
pickup, 114  
pickup-retry-interval, 114  
pix-bug-workaround, 105  
postmaster, 29  
process-x-dkim-options, 49  
process-x-envid, 48, 116  
process-x-job, 49, 116  
process-x-virtual-mta, 50, 115  
324  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
queue-priority, 75  
queue-to, 80  
rcpt-to, 122  
record-fields, 68  
records, 67  
reenable-source-ip-after, 89  
reject-mfrom-check-fail, 100  
reject-mfrom-check-permerror, 100  
reject-mfrom-check-temperror, 99  
relay-address, 33  
relay-debug, 34  
relay-domain, 33  
remove-header, 38  
require-auth, 38  
require-starttls, 102  
require-starttls-before-auth, 39  
reroute-to-virtual-mta, 127  
reserved-smtp-in, 52  
retain-x- virtual-mta, 50  
retain-x-job, 50  
retry-after, 87  
retry-interval, 65  
retry-upon-new-mail, 105  
route, 106  
run-as-root, 37  
smtp-421-means-mx-unavailable, 98  
smtp-553-means-invalid-mailbox, 97  
smtp-await-slot, 51  
smtp-data-termination-timeout, 96  
smtp-greeting-timeout, 100  
smtp-ip, 52  
smtp-listener, 54  
smtp-pattern-list, 108  
smtp-port, 53  
smtp-server-tls-certificate, 39  
smtp-service, 55  
smtp-source-host, 109  
smtp-source-ip, 108  
source, 40  
source-group, 51  
spool, 30  
spool-delete-corrupted, 31  
spool-max-files, 31  
spool-max-recipients, 32  
sync, 69  
sync-msg-create, 129  
sync-msg-update, 129  
thread-max-priority, 130  
thread-min-priority, 130  
thread-reuse, 130  
too-many-rcpts-fails-message, 48  
trace-dkim-check, 42  
trace-domainkeys-check, 42  
trace-mfrom-check, 42  
trace-pra-check, 42  
type, 94  
user-string, 65, 72  
use-starttls, 101  
use-unencrypted-plain-auth, 97  
verp-default, 41  
325  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
virtual-mta, 95  
world-readable, 68  
write-timeout, 66  
bounce-processor  
deliver-email, 34  
forward-errors-to, 35  
forward-unmatched-to, 34  
deprecated  
acct-auto-rotation, 69  
acct-file, 70  
acct-log-header, 70  
acct-move-interval, 71  
acct-move-max-size, 72  
acct-rotate, 70, 71  
acct-user-string, 72  
spool, 30  
domain  
allow-cancel-during-transfer, 96  
allow-priority-interruption, 75  
allow-priority-interruption-during-transfer, 75  
assume-delivery-upon-data-termination-timeout, 97, 108  
auth-password, 97  
auth-username, 96  
backoff-max-connect-rate, 105  
backoff-max-msg-per-hour, 87  
backoff-max-msg-rate, 86  
backoff-notify, 88  
backoff-reroute-to-virtual-mta, 93  
backoff-retry-after, 87  
backoff-to-normal-after, 88  
backoff-to-normal-after-delivery, 88  
backoff-upon-all-sources-disabled, 89  
bounce-after, 75  
bounce-upon-5xx-greeting, 98  
bounce-upon-no-mx, 98  
bounce-upon-pix-transfer-failure, 99  
bounce-upon-transfer-failure, 99  
check-mfrom-outbound, 43  
check-pra-outbound, 44  
command, 113  
connect-timeout, 100  
data-send-timeout, 101  
default-smtp-port, 108  
deliver-local-dsn, 74  
delivery-priority, 76  
dkim-identity, 77  
dkim-identity-fallback, 78  
dkim-sign, 76  
dk-sign, 76  
file-destination, 111  
file-format, 110  
ignore-8bitmime, 101  
ignore-chunking, 102  
ignore-pipelining, 102  
include, 128  
326  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
log-commands, 60, 82  
log-connections, 59, 81  
log-data, 61, 83  
log-resolution, 46, 59  
log-tls, 80  
log-transfer-failures, 47, 62  
max-cold-virtual-mta-msg, 92  
max-connect-rate, 105  
max-errors-per-connection, 43  
max-events-recorded, 63, 84  
max-msg-per-connection, 103  
max-msg-per-hour, 87  
max-msg-rate, 86  
max-rcpt-per-message, 103  
max-rcpt-per-transaction, 103  
max-smtp-out, 104  
max-smtp-out-per-source-ip, 104  
pix-bug-workaround, 105  
queue-priority, 75  
queue-to, 80  
reenable-source-ip-after, 89  
remove-header, 38  
require-starttls, 102  
reroute-to-virtual-mta, 127  
retry-after, 87  
retry-upon-new-mail, 105  
route, 106  
smtp-421-means-mx-unavailable, 98  
smtp-553-means-invalid-mailbox, 97  
smtp-data-termination-timeout, 96  
smtp-greeting-timeout, 100  
smtp-pattern-list, 108  
type, 94  
use-starttls, 101  
use-unencrypted-plain-auth, 97  
feedback-loop-processor  
deliver-email, 34  
forward-errors-to, 35  
forward-unmatched-to, 34  
global  
acct-auto-rotation, 69  
acct-file, 70  
acct-log-header, 70  
acct-move-interval, 71  
acct-move-max-size, 72  
acct-rotate, 70, 71  
acct-user-string, 72  
acct-write-msgDlv, 73  
domain-key, 79  
domain-macro, 94  
domain-suffix, 127  
dummy-smtp-await-slot, 118  
dummy-smtp-has-chunking, 118  
dummy-smtp-has-pipelining, 119  
dummy-smtp-has-verp, 119  
dummy-smtp-ip, 118  
327  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
dummy-smtp-latency, 119  
dummy-smtp-port, 118  
dummy-smtp-update-stats, 119  
host-id, 126  
host-name, 128  
http-access, 56  
http-log-data, 57  
http-log-requests, 57  
http-mgmt-port, 56  
http-mgmt-source, 57  
include, 128  
invalid-virtual-mta-fallback, 80  
log-auto-rotation, 57  
log-file, 58  
log-file-world-readable, 62  
log-rotate, 58  
mx-connection-limit, 107  
name-server, 129  
no-http-mgmt-source, 57  
pickup, 114  
pickup-retry-interval, 114  
postmaster, 29  
relay-address, 33  
relay-debug, 34  
relay-domain, 33  
run-as-root, 37  
smtp-await-slot, 51  
smtp-ip, 52  
smtp-listener, 54  
smtp-port, 53  
smtp-server-tls-certificate, 39  
smtp-source-ip, 108, 109  
spool, 30  
spool-delete-corrupted, 31  
spool-max-files, 31  
spool-max-recipients, 32  
sync-msg-create, 129  
sync-msg-update, 129  
thread-max-priority, 130  
thread-min-priority, 130  
thread-reuse, 130  
user-string, 72  
pattern-list  
header, 121  
include, 128  
mail-from, 121  
rcpt-to, 122  
smtp-user  
authentication-method, 40  
password, 40  
source, 40  
source  
accept-invalid-recipients, 95  
add-date-header, 36  
add-message-id-header, 37  
328  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
add-received-header, 37  
allow-auth, 37  
allow-mailmerge, 38  
allow-starttls, 39  
allow-unencrypted-plain-auth, 39  
always-allow-api-submission, 114  
always-allow-relaying, 32  
auto-qualify-domain, 125  
bcc, 36  
broken-auth-clients, 40  
check-dkim-inbound, 41  
check-domainkeys-inbound, 41  
check-mfrom-inbound, 43  
check-mfrom-inbound-best-guess, 44  
check-pra-inbound, 44  
check-pra-inbound-best-guess, 44  
date-header-time, 36  
default-virtual-mta, 45  
disconnect-on-transient-error, 46  
dsn-return-default, 45  
hide-message-source, 46  
include, 128  
jobid-header, 49  
log-commands, 60, 82  
log-connections, 59, 81  
log-data, 61, 83  
log-tls, 80  
max-message-hops, 47  
max-message-size, 47  
max-rcpt-per-message, 47, 103, 112  
pattern-list, 48  
process-x-dkim-options, 49  
process-x-envid, 48  
process-x-job, 49  
process-x-virtual-mta, 50  
reject-mfrom-check-fail, 100  
reject-mfrom-check-permerror, 100  
reject-mfrom-check-temperror, 99  
remove-header, 38  
require-auth, 38  
require-starttls-before-auth, 39  
retain-x- virtual-mta, 50  
retain-x-job, 50  
smtp-service, 55  
source-group, 51  
too-many-rcpts-fails-message, 48  
trace-dkim-check, 42  
trace-domainkeys-check, 42  
trace-mfrom-check, 42  
trace-pra-check, 42  
verp-default, 41  
source {pickup}  
add-message-id-header, 116  
add-received-header, 117  
default-virtual-mta, 115  
dsn-return-default, 115  
hide-message-source, 117  
pattern-list, 117  
329  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)  
process-x-envid, 116  
process-x-job, 116  
process-x-virtual-mta, 115  
source-group  
max-smtp-in, 52  
reserved-smtp-in, 52  
spool  
delete-file-holders, 30  
deliver-only, 31  
min-free-space, 31  
virtual-mta  
auto-cold-virtual-mta, 90  
cold-virtual-mta, 91  
domain-key, 79  
host-name, 128  
include, 128  
include-headers-from, 94  
max-smtp-msg-rate, 85  
max-smtp-out, 104  
smtp-source-host, 109  
smtp-source-ip, 108  
virtual-mta-pool  
virtual-mta, 95  
330  
© 2012, Port25 Solutions, Inc. This document contains confidential and proprietary information belonging  
to Port25 Solutions, Inc. Not for release or distribution without permission. (v.2012-03-08-01)